swagger-ui快速入门教程

mac2024-05-19 32

title: swagger ui快速入门教程 catalog: true date: 2019-10-31 15:30:54 subtitle: 通过使用易水公共组件快速开启和关闭swagger ui，生成软件接口说明文档 header-img: http://static.yishuifengxiao.com/blog/global/backgroup/article.jpg tags:

spring security易水组件 catagories:spring security

快速启动

1 引入相关依赖

<dependency> <groupId>com.yishuifengxiao.common</groupId> <artifactId>common-spring-boot-starter</artifactId> <version>4.1.2</version> </dependency>

2 开启配置

在配置文件中加入以下配置即可快速开启 swagger-ui 功能。

yishuifengxiao.swagger.base-package= 需要扫描的控制器代码的路径

加入上述配置后即可通过 http://ip:port/doc.html 查看 swagger-ui 增强文档。

也可以通过 http://ip:port/swagger-ui.html 查看 swagger-ui 原生文档。

此外，也可以通过http://ip:port/v2/api-docs查看元数据

这里只是简化了 swagger-ui 的扫描注解，对于软件开发过程中必须 swagger-ui 其他 API 注解仍然不可省略。

下面是一个简单的 swagger-ui 配置文档示例

@Api(value = "【测试接口】测试接口", tags = {"测试接口"}) @Valid @Controller @RequestMapping @Slf4j public class WebConftroller { @ApiImplicitParams({ @ApiImplicitParam(name = "username", value = "登录的用户名"), @ApiImplicitParam(name = "loginIp", value = "登录ip"), @ApiImplicitParam(name = "pass", value = "登录结果,true表示成功，false失败"), @ApiImplicitParam(name = "pageSize", value = "分页大小,分页的大小不能小于1,默认值为20"), @ApiImplicitParam(name = "pageNum", value = "当前页的页码,页码的大小不能小于1，默认值为1")}) @ApiOperation(value = "分页查询登录记录", notes = "分页查询登录记录") @GetMapping("/demo") @ResponseBody public Response<String> findPage( HttpServletRequest request, HttpServletResponse response, @RequestParam(value = "username", required = false) String username, @RequestParam(value = "loginIp", required = false) String loginIp, @RequestParam(value = "pass", required = false) Boolean pass, @RequestParam(name = "pageSize", defaultValue = "20", required = false) Integer pageSize, @RequestParam(name = "pageNum", defaultValue = "1", required = false) Integer pageNum) { return Response.suc(); } }

特别鸣谢：

此项功能中的 doc.html 界面中功能使用到了刀哥的 swagger-bootstrap-ui 中的功能，在此特别感谢刀哥的大力支持，关于 swagger-bootstrap-ui 的详细说明请参见刀哥的 swagger-bootstrap-ui 文档

配置参数

# swagger-ui文档的标题 yishuifengxiao.swagger.title=API接口文档 # swagger-ui文档描述 yishuifengxiao.swagger.description=易水风萧接口说明文档 #swagger-ui 项目服务的url yishuifengxiao.swagger.terms-of-service-url=http://www.yishuifengxiao.com/ # swagger-ui 文档分组的名字 yishuifengxiao.swagger.group-name=default # swagger-ui 文档版本 yishuifengxiao.swagger.version=1.0.0 # 项目联系人名字 yishuifengxiao.swagger.contact-user=yishuifengxiao # 项目联系的url yishuifengxiao.swagger.contact-url=http://www.yishuifengxiao.com/ # 项目联系邮箱 yishuifengxiao.swagger.contact-email=zhiyubujian@163.com

以上常规配置都有缺省默认值，用户在使用易水风萧通用组件时，如果没有特别需要，使用默认配置即可。

进阶配置

一般情况下，使用 swagger-ui 的常规配置即可满足日常开发需要，但是在某些情况下，可能需要一些高级配置。如，需要通过在所有的 API 接口上批量加上一个默认参数，此时即可用通用组件的高级配置功能了。

yishuifengxiao.swagger.contact.auths[0].name=Authorization yishuifengxiao.swagger.contact.auths[0].description=自定义必填请求头 yishuifengxiao.swagger.contact.auths[0].modelRef=string yishuifengxiao.swagger.contact.auths[0].parameterType=header yishuifengxiao.swagger.contact.auths[0].required=false

上述示例配置在 API 文档中的所有请求中批量添加了一个参数名为 Authorization 的请求头参数。

yishuifengxiao.swagger.contact.auths 是一个数组，可以添加多个配置，更多详细配置可参见参见 swagger-ui 的 ParameterBuilder 用法配置

资源链接

易水公共组件官方文档地址：http://doc.yishuifengxiao.com

易水公共组件源码地址：https://gitee.com/zhiyubujian/common-starter

易水风萧个人博客 http://www.yishuifengxiao.com