swagger-ui

快速启动

在配置文件中加入以下配置即可快速开启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文档 (opens new window)

配置参数

# 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.auths[0].name=Authorization
yishuifengxiao.swagger.auths[0].description=自定义必填请求头
yishuifengxiao.swagger.auths[0].modelRef=string
yishuifengxiao.swagger.auths[0].parameterType=header
yishuifengxiao.swagger.auths[0].required=false

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

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

开启登陆校验

正常情况下，在生产环境里需要去除掉swagger-ui界面，但是在有时候又需要根据swagger进行一下简单地调试，这样直接将swagger-ui界面暴露在生产环境中是十分危险的，这时候可以开启登陆校验功能，只有用户输入了正确的口令才能进入到swagger展示页面。

开启方法如下

# 登陆的用户名，默认为admin
yishuifengxiao.swagger.username=admin
# 登陆的密码
yishuifengxiao.swagger.password=登陆密码

访问swagger页面时需要输入的用户名，默认值为admin，如果该用户名为空表示则不开启认证功能。只有username和password参数均不为空时才会开启认证功能