knife4j-Swagger

knife4j 是 Swagger 生成 API 文档的增强解决方案，最主要是 knife4j 提供了动态字段注释功能来实现 Map 来接收参数这个的接口文档生成，忽略参数属性来实现同一个实体类对不同接口生成不同的文档。

配置

• 引入 jar 包

  <dependency>
      <groupId>com.github.xiaoymin</groupId>
      <artifactId>knife4j-spring-boot-starter</artifactId>
      <version>3.0.2</version>
  </dependency>
  

• 添加注释来开启 knife4j

  @Configuration
  @EnableOpenApi 
  @Import(BeanValidatorPluginsConfiguration.class)
  public class SwaggerConfig {
  
      @Bean
      public Docket createRestApi() {
          ...
      }
  
      private ApiInfo apiInfo() {    
      }
  

  完整的实例如下：

  @Configuration
  @EnableOpenApi 
  @Import(BeanValidatorPluginsConfiguration.class)
  public class SwaggerConfig {
  
      @Bean
      public Docket createRestApi() {
          return new Docket(DocumentationType.OAS_30)
              .apiInfo(apiInfo())
              .select()
              .apis(RequestHandlerSelectors.basePackage("xxx.yyy.zzz"))
              .paths(PathSelectors.any())
              .build();
      }
  
      private ApiInfo apiInfo() {
          return new ApiInfoBuilder()
              .title("test")
              .description("接口")
              .termsOfServiceUrl("http://localhost:8080/doc.html")
              .version("1.0")
              .build();
      }
  
  }
  

• 如果遇到了访问 404，那么进行静态资源拦截配置

  @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/");
      }
  }
  

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

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

忽略参数属性

• 提供两个 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());
  }
  

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

  @ApiModel
  public class Student {
  
      @ApiModelProperty(value="主键")
      private String id;
  
      @ApiModelProperty(value="姓名")
      private String name;
  
      @ApiModelProperty(value="年龄")
      private Integer age;
  
      @ApiModelProperty(value="性别")
      private String gender;
  
      ...
  }
  

自动生成文档如下：