SpringBoot2.7.12整合Knife4j

• 是什么

  Knife4j是一个集Swagger2 和 OpenAPI3为一体的增强解决方案

• 添加依赖

  <!--引入Knife4j的官方start包,该指南选择Spring Boot版本<3.0,开发者需要注意-->
  <dependency>
      <groupId>com.github.xiaoymin</groupId>
      <artifactId>knife4j-openapi2-spring-boot-starter</artifactId>
      <version>4.0.0</version>
  </dependency>
  

• 创建配置类

  package com.example.demospringbootdemo.config;
  
  @Configuration
  @EnableSwagger2WebMvc
  public class Knife4jConfiguration {
      @Bean(value = "dockerBean")
      public Docket dockerBean() {
          //指定使用Swagger2规范
          Docket docket=new Docket(DocumentationType.SWAGGER_2)
                  .apiInfo(new ApiInfoBuilder()
                          //描述字段支持Markdown语法
                          .description("# Knife4j RESTful APIs")
                          .termsOfServiceUrl("https://itl-coder.github.io/")
                          .contact("ituninapp@gmail.com")
                          .version("1.0")
                          .build())
                  //分组名称
                  .groupName("用户服务")
                  .select()
                  //这里指定Controller扫描包路径
                  .apis(RequestHandlerSelectors.basePackage("com.example.demospringbootdemo.controller"))
                  .paths(PathSelectors.any())
                  .build();
          return docket;
      }
  }
  

  • 分组配置

    // @Bean public Docket deptDockerBean() { 部门管理的配置 }
    .groupName("部门管理").paths(PathSelectors.ant("/dept/**"))
    // @Bean public Docket empDockerBean() { 用户管理的配置 }
    .groupName("用户管理").paths(PathSelectors.ant("/emp/**"))
    

    

• 控制器的使用

  • 实体类参数

    @RestController
    @Api(tags = "用户管理", description = "提供用户信息的接口")
    public class UserController {
        @ApiOperation(value = "对接口功能的说明", notes = "根据用户传入的信息返回用户对象")
        @GetMapping("/user")
        public User sayUser(User user) {
            return user;
        }
    }
    

    

  • 普通字段

    package com.example.demospringbootdemo.controller;
    
    
    @RestController
    @Api(tags = "用户管理", description = "提供用户信息的接口")
    public class UserController {
        @ApiOperation(value = "对接口功能的说明")
        @GetMapping("/hello")
        public String sayHello(
                @ApiParam(name = "username", required = false, defaultValue = "coder-itl") String username,
                @ApiParam(name = "password", required = true, defaultValue = "123") String password) {
            return username + " " + password;
        }
    }
    

• 实体类使用

  @Data
  @NoArgsConstructor
  @AllArgsConstructor
  @ApiModel(value = "用户实体")
  public class User {
      @ApiModelProperty(value="姓名",example="张飞")
      private String username;
      @ApiModelProperty(value="密码",example="123",required = true)
      private Integer password;
  }
  
  

  

• 启动

  http://localhost:8080/doc.html
  

• 如何添加了拦截器,进行如下配置

  package com.example.demospringbootdemo.config;
  
  // @EnableWebMvc 不启用
  @Configuration
  public class SpringMvcConfig implements WebMvcConfigurer {
      @Autowired
      private GlobalInterceptor globalInterceptor;
  
      // 拦截器配置
      @Override
      public void addInterceptors(InterceptorRegistry registry) {
          registry.addInterceptor(globalInterceptor);
      }
      
      @Override
      public void addResourceHandlers(ResourceHandlerRegistry registry) {
          registry.addResourceHandler("doc.html").addResourceLocations("classpath:/META-INF/resources/");
          registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
      }
  }