SpringBoot整合knife4j

SpringBoot整合knife4j

1. 导入依赖

   <!-- 在需要的项目中导入依赖 -->
   <dependencies>
       <dependency>
           <groupId>com.github.xiaoymin</groupId>
           <artifactId>knife4j-spring-boot-starter</artifactId>
           <version>2.0.2</version>
       </dependency>
   </dependencies>
   

2. 添加配置类 创建一个swagger2的配置类

   @Configuration
   @EnableSwagger2
   @EnableKnife4j
   @Import(BeanValidatorPluginsConfiguration.class)
   public class SwaggerConfig {
       @Bean(value = "createRestApi")
       public Docket createRestApi() {
           return new Docket(DocumentationType.SWAGGER_2)
                   .apiInfo(new ApiInfoBuilder()
                           //标题
                           .title("日志处理")
                           //版本信息
                           .version("9.0")
                           //描述消息
                           .description("日志处理")
                           .contact(new Contact("xxxx", "http://www.xxxx.com/", "http://www.xxx.com/"))
                           .license("重庆xxx技术有限公司")
                           .licenseUrl("http://www.xxxx.com/")
                           .build())
                   //最终调用接口后会和paths拼接在一起
                   .pathMapping("/")
                   .select()
                   //包路径
                   .apis(RequestHandlerSelectors.basePackage("com.xxxx.controller"))
                   //过滤的接口
                   .paths(PathSelectors.any())
                   .build();
       }
   }
   

3. 创建接口

   Swagger2相关的注解其实并不多，而且很容易懂，下面我来分别向小伙伴们举例说明：

   @RestController
   @Api(tags = "用户管理相关接口")
   @RequestMapping("/user")
   public class UserController {
   
       @PostMapping("/")
       @ApiOperation("添加用户的接口")
       @ApiImplicitParams({
               @ApiImplicitParam(name = "username", value = "用户名", defaultValue = "李四"),
               @ApiImplicitParam(name = "address", value = "用户地址", defaultValue = "深圳", required = true)
       }
       )
       public RespBean addUser(String username, @RequestParam(required = true) String address) {
           return new RespBean();
       }
   
       @GetMapping("/")
       @ApiOperation("根据id查询用户的接口")
       @ApiImplicitParam(name = "id", value = "用户id", defaultValue = "99", required = true)
       public User getUserById(@PathVariable Integer id) {
           User user = new User();
           user.setId(id);
           return user;
       }
       @PutMapping("/{id}")
       @ApiOperation("根据id更新用户的接口")
       public User updateUserById(@RequestBody User user) {
           return user;
       }
   }
   

   这里边涉及到多个API，我来向小伙伴们分别说明：

   @Api注解可以用来标记当前Controller的功能。
   @ApiOperation注解用来标记一个方法的作用。
   @ApiImplicitParam注解用来描述一个参数，可以配置参数的中文含义，也可以给参数设置默认值，这样在接口测试的时候可以避免手动输入。
   如果有多个参数，则需要使用多个@ApiImplicitParam注解来描述，多个@ApiImplicitParam注解需要放在一个@ApiImplicitParams注解中。
   需要注意的是，@ApiImplicitParam注解中虽然可以指定参数是必填的，但是却不能代替@RequestParam(required = true)，前者的必填只是在Swagger2框架内必填，抛弃了Swagger2，这个限制就没用了，所以假如开发者需要指定一个参数必填，@RequestParam(required = true)注解还是不能省略。

   如果参数是一个对象（例如上文的更新接口），对于参数的描述也可以放在实体类中。例如下面一段代码：

   @ApiModel
   public class User {
       @ApiModelProperty(value = "用户id")
       private Integer id;
       @ApiModelProperty(value = "用户名")
       private String username;
       @ApiModelProperty(value = "用户地址")
       private String address;
       //getter/setter
   }
   

4. 在Security中的配置

   资源	说明
   /doc.html	SwaggerBootstrapUi提供的文档访问地址
   /api-docs-ext	SwaggerBootstrapUi提供的增强接口地址
   /swagger-resources	Springfox-Swagger提供的分组接口
   /api-docs	Springfox-Swagger提供的分组实例详情接口
   /swagger-ui.html	Springfox-Swagger提供的文档访问地址
   /swagger-resources/configuration/ui	Springfox-Swagger提供
   /swagger-resources/configuration/security	Springfox-Swagger提供

   如果我们的Spring Boot项目中集成了Spring Security，那么如果不做额外配置，Swagger2文档可能会被拦截，此时只需要在Spring Security的配置类中重写configure方法，添加如下过滤即可：

   /***
        * Http安全配置，对每个到达系统的http请求链接进行校验
        * @param http
        * @throws Exception
        */
       @Override
    public void configure(HttpSecurity http) throws Exception {
           //所有请求必须认证通过
        http.authorizeRequests()
                   //下边的路径放行
                   .antMatchers("/swagger-resources/**","/api-docs","/doc.html","/api-docs-ext","/webjars/**","/v2/**","/swagger-ui.html") //配置地址放行
                   .permitAll()
                   .anyRequest()
                   .authenticated();    //其他地址需要认证授权
       }
   

5.如果是springboot项目，部署到生产系统,为了接口安全,需要屏蔽所有Swagger的相关资源，只需要在配置文件中添加：

knife4j:
  production: true

此时启动项目，输入http://localhost:8080/doc.html就行了

参考博客：https://doc.xiaominfo.com/knife4j/springboot.html#maven%E5%BC%95%E7%94%A8