knife4j-swagger

knife4j 是 Swagger 生成 API 文档的增强解决方案，knife4j 对原生 swagger 的增强体现在：

• 提供了新的一套 Web 页面，更符合绝大多数人的使用习惯和审美；
• 补充了一些注解，扩展了原生 Swagger 的功能；
• 提供了动态字段注释功能来实现 Map 来接收参数这个的接口文档生成；
• 忽略参数属性来实现同一个实体类对不同接口生成不同的文档等诸如此类的小改进。

在越来越多的产品出现后，knife4j 的优势和特点慢慢地变得稀松平常起来了…

第 1 步：引入 jar 包

<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-spring-boot-starter</artifactId>
    <version>3.0.2</version>    <!--  for swagger 3 -->
<!--<version>2.0.9</version>--> <!--  for swagger 2 -->
</dependency>

第 2 步：添加注释来开启 knife4j

@Configuration
@EnableOpenApi
@Import(BeanValidatorPluginsConfiguration.class)
public class SwaggerConfig {

  // 其它内容一切照旧
  ....

}

第 3 步：验证

knife4j 有提供 UI 来显示，默认访问地址是：

http://$host:${port}/doc.html

问题解决

• 整合 spring-security 出现的“访问权限问题”解决

.antMatchers("/doc.html", "/webjars/**", "/swagger-ui/**", "/v3/api-docs/**",  "/swagger-resources/**").permitAll()

• Spring MVC 中可能的“静态资源拦截问题”解决

@Configuration
public class WebMvcConfig implements WebMvcConfigurer {

  @Override
  public void addResourceHandlers(ResourceHandlerRegistry registry) {
    registry.addResourceHandler("doc.html").addResourceLocations("classpath:/META-INF/resources/");
    registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
  }
}

新增功能：@ApiOperationSupport 注解

@ApiOperationSupport 注解是扩展增强注解，目前主要扩展的属性有 order（接口排序）、author（接口开发者）、params（动态字段集合）、responses（返回动态字段集合）、ignoreParameters 。

它是配合后续其它新增注解使用的。

新增功能：@DynamicParameters 注解

knife4j 官方不建议使用该功能，因为这个功能比较简陋，仅适用于较为简单的场景。

这是两个可以帮大家"偷懒"的注解：如果 Controller 的方法的参数有多个，但是大家又懒得去定义 FO 时，可以会使用 Map 来"收"参数。

这种情况下，可以使用 @DynamicParameters 来生成 map 的说明文档：

@PostMapping("/test1")
@ApiOperationSupport(params = @DynamicParameters(properties = {
    @DynamicParameter(name = "name", value = "名字", example = "张三"),
    @DynamicParameter(name = "sex", value = "性别", example = "女"),
    @DynamicParameter(name = "age", value = "年龄", example = "20")
}))
public void test1(@RequestBody Map<String, Object> map) {

    String name = (String) map.get("name");
    String sex = (String) map.get("sex");
    Integer age = (Integer) map.get("age");

    log.info("姓名:" + name);
    log.info("性别:" + sex);
    log.info("年龄:" + age);
}

自动生成接口文档如下：

注意
@DynamicParameters 注解的功能比较简陋，只支持简单的情况。即，如果又更深层次、更复杂的嵌套关系，它就不好使了。

knif4j 的作者也是提醒大家不要滥用这个功能。

忽略参数属性

• 提供两个 URI 接口作对比

@PostMapping("/test3")
public void test3(@RequestBody Student student) {
  log.info(student.toString());
}

@PostMapping("/test4")
@ApiOperationSupport(ignoreParameters = {"id"})
public void test4(@RequestBody Student student) {
  log.info(student.toString());
}

• 自定义用于参数绑定的实体类

@Schema(description = "学生信息")
public class Student {

  @Schema(name = "主键")
  private String id;

  @Schema(name = "姓名")
  private String name;

  @Schema(name = "年龄")
  private Integer age;

  @Schema(name = "性别")
  private String sex;

  ...

}

自动生成文档如下：