微服务网关(Zuul)聚合Swagger以及Swagger注解的使用

• 微服务网关聚合Swagger
• • 1、Zuul网关中的配置
  • • 1、导入依赖
    • 2、application.yml添加配置
    • 3、配置扫描微服务swagger文档
    • 4、配置Swagger
  • 2、微服务中的配置
  • • 1、导入依赖
    • 2、配置Swagger
    • 3、SpringSecurity环境放行Swagger
    • 4、Oauth2环境放行Swagger
    • 5、效果展示
  • 3、Swagger实战场景
  • • 1、自定义注解实现接口跳过Swagger扫描
    • 2、Swagger注解的使用
    • 3、使用Swagger参数注解出现的问题
    • • 参数请求类型
      • Post请求中参数请求类型Body问题
      • 总结

    io.springfox
    springfox-swagger2
    2.6.1



    com.github.xiaoymin
    swagger-bootstrap-ui
    1.9.6

注意swagger.servers.location中的路径与zuul网关路由转发的路径匹配重点

zuul:
  routes:
    CHAOSHAN-AUTH:
     path: /authfavicon.ico", "/index",
                    "/swagger-resources/configuration/ui",//用来获取支持的动作
                    "/swagger-resources",//用来获取api-docs的URI
                    "/swagger-resources/configuration/security",//安全选项
                    "/swagger-ui.html", "/doc.html").permitAll()
            .antMatchers("
  @ApiModelProperty(name = "主键(id)",value = "主键",required = false,example = "111",hidden = false)
  private Long id;
}

@Api 标注在Controller上

@ApiOperation 标注在方法上

@ApiParam 标注在方法的参数上，或者说添加在参数前面

@ApiImplicitParam 标注在方法上，同样描述的是方法的参数，与@ApiParam的区别在于，@ApiParam是放在参数旁，而@ApiImplicitParam是放在方法上的，不过需要绑定参数名

@ApiImplicitParams 标注在方法上，如果方法有多个参数，需要使用这个值是数组类型的@ApiImplicitParam

@GetMapping(value = "/r3")
@ApiOperation(value = "r3接口")
@ApiImplicitParam(name = "m", value = "参数描述m", required = false, paramType = "String1")
public String r3(@ApiParam(value = "m1") String m) {
    return "r3";
}

@GetMapping(value = "/r4")
@ApiOperation(value = "r4接口")
@ApiImplicitParams(
    value = { @ApiImplicitParam(name = "m", value = "参数m描述", required = false, paramType = "Integer"),
             @ApiImplicitParam(name = "n", value = "参数n描述", required = true, paramType = "String(字符串)")}
)
public String r4(String m, String n) {
    return "r4";
}

如果使用了@ApiImplicitParams 或者@ApiImplicitParam注解，就会在swagger改变原来的参数请求方式，不管你是query，form，还是pathvariable通过改成body的形式传递参数

@GetMapping(value = "/r4")
@ApiOperation(value = "r4接口")
@ApiImplicitParams(
    value = { @ApiImplicitParam(name = "m", value = "参数m描述", required = false),
             @ApiImplicitParam(name = "n", value = "参数n描述", required = true)}
)
public String r4(@RequestParam String m,@RequestParam String n) {
    return "r4";
}

​ 可以发现如果使用了@ApiImplicitParams对参数声明到swagger的注解，就会出现swagger传递方式绑定为body的情况，这个时候就需要在@ApiImplicitParam中声明参数传递类型

@GetMapping(value = "/r4")
@ApiOperation(value = "r4接口")
@ApiImplicitParams(
    value = { @ApiImplicitParam(name = "m", value = "参数m描述", required = false,paramType = "query"),
             @ApiImplicitParam(name = "n", value = "参数n描述", required = true,paramType = "query")}
)
public String r4(@RequestParam String m,@RequestParam String n) {
    return "r4";
}

如果是Post请求中携带参数@RequestBody实体不建议使用@ApiParam和@ApiImplicitParam，为什么呢？

举个例子大家就明白了！

@PostMapping("/user")
@ApiImplicitParam(name = "user",paramType = "body")
public User getUser(@RequestBody User user){
    User user1 = new User();
    return user1;
}

我把@ApiImplicitParam注释后

@PostMapping("/user")
// @ApiImplicitParam(name = "user",paramType = "body")
public User getUser(@RequestBody User user){
  User user1 = new User();
  return user1;
}

总结一下，为了加快前后端的开发速度，我们使用Swagger的接口测试文档，对于接口中参数的类型不能光凭前端人员去猜测，我们后端开发人员应该给出明确的提示

所以为了规范化，会在接口中的参数添加@ApiParam注解，但是这个注解是需要写在方法参数的左侧，如果说这个参数需要做一定约束的话，需要添加@RequestParam、@RequestBody、@PathVariable等，最后就是下面这种代码

@GetMapping("/")
public String test(@ApiParam(name="",value="",require="") @RequestParam String a){}

看起来很乱，而且这仅仅是一个参数而已，并且@ApiParam的参数还不够丰富，所以开发中我们更推荐使用@ApiImplicitParam，如果方法中只有一个参数则使用它，如果是2个参数以上，需要使用@ApiImplicitParams，传入数组类型的@ApiImplicitParam，演示如下

@GetMapping("/")
@ApiImplicitParams({
    @ApiImplicitParam(name="a",value="",required=false,paramType="query"),
    @ApiImplicitParam(name="b",value="",required=false,paramType="query")
})
public String test(@RequestParam String a,@RequestParam String b){}

这样看起来是不是简洁许多，减少了些许代码冗余，并且还能够指定swagger参数请求类型
如果你对本文的内容有疑问或者其他方面的见解，欢迎到评论区里留言