【SpringBoot】廿二、SpringBoot中整合knife4j接口文档

淡淡的烟草味﹌ 2023-02-22 08:07 114阅读 0赞

**在项目开发中，web项目的前后端分离开发，APP开发，需要由前后端工程师共同定义接口，编写接口文档，之后大家都根据这个接口文档进行开发，到项目结束前都要一直维护**

**接口文档使得项目开发过程中前后端工程师有一个统一的文件进行沟通交流开发，项目维护中或者项目人员更迭，方便后期人员查看、维护**

## 一、界面先赏 ##

### 1、首页 ###

![首页][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzQwMDY1Nzc2_size_16_color_FFFFFF_t_70]

### 2、接口文档 ###

![接口文档][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzQwMDY1Nzc2_size_16_color_FFFFFF_t_70 1]

### 3、调试 ###

![调试][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzQwMDY1Nzc2_size_16_color_FFFFFF_t_70 2]

## 二、整合 knife4j ##

### 1、引入 maven 依赖 ###

<dependency>
        <groupId>com.github.xiaoymin</groupId>
        <artifactId>knife4j-spring-boot-starter</artifactId>
        <version>2.0.2</version>
    </dependency>
    
    <dependency>
        <groupId>com.google.guava</groupId>
        <artifactId>guava</artifactId>
        <version>29.0-jre</version>
    </dependency>

一般情况我们只需要引入 knife4j 的依赖即可，但是有时会出现 guava 的版本冲突，所以，我们把 guava 一起引入进来

### 2、knife4j 配置文件 ###

创建 Knife4jConfig 文件

import org.springframework.context.annotation.Bean;
    import org.springframework.context.annotation.Configuration;
    import springfox.documentation.builders.ApiInfoBuilder;
    import springfox.documentation.builders.PathSelectors;
    import springfox.documentation.builders.RequestHandlerSelectors;
    import springfox.documentation.service.ApiInfo;
    import springfox.documentation.spi.DocumentationType;
    import springfox.documentation.spring.web.plugins.Docket;
    import springfox.documentation.swagger2.annotations.EnableSwagger2;
    
    /** * knife4j 配置 * * @Author Lizhou */
    @Configuration
    @EnableSwagger2
    public class Knife4jConfig { 
    
        @Bean
        public Docket createRestApi() { 
            return new Docket(DocumentationType.SWAGGER_2)
                    .apiInfo(apiInfo())
                    .select()
                    .apis(RequestHandlerSelectors.basePackage("com.zyxx"))
                    .paths(PathSelectors.any())
                    .build();
        }
    
        private ApiInfo apiInfo() { 
            return new ApiInfoBuilder()
                    .title("SpringBoot项目 后台服务API接口文档")
                    .description("使用 knife4j 搭建的后台服务API接口文档")
                    .termsOfServiceUrl("http://localhost:8080/")
                    .contact("lizhou")
                    .version("1.0.0")
                    .build();
        }
    }

整体配置与 Swagger2 几乎一致，扫描 controller 所在的包

### 3、启动类 ###

import org.mybatis.spring.annotation.MapperScan;
    import org.springframework.boot.SpringApplication;
    import org.springframework.boot.autoconfigure.SpringBootApplication;
    import org.springframework.boot.autoconfigure.condition.ConditionalOnClass;
    import org.springframework.context.annotation.ComponentScan;
    import org.springframework.scheduling.annotation.EnableScheduling;
    import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
    import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;
    import springfox.documentation.spring.web.SpringfoxWebMvcConfiguration;
    
    @SpringBootApplication
    @ConditionalOnClass(SpringfoxWebMvcConfiguration.class)
    public class SbmApplication implements WebMvcConfigurer { 
    
        public static void main(String[] args) { 
            SpringApplication.run(SbmApplication.class, args);
        }
    
        @Override
        public void addResourceHandlers(ResourceHandlerRegistry registry) { 
            registry.addResourceHandler("doc.html").addResourceLocations("classpath:/META-INF/resources/");
            registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
        }
    }

我们需要开放其静态资源的访问，启动类实现 WebMvcConfigurer 接口，重写 addResourceHandlers 方法

### 4、访问文档 ###

启动项目，访问路径

http://localhost:8080/doc.html

## 三、注意 ##

访问时，如果提示 knife4j 文档异常，检查下自己的拦截器是否没有放开 knife4j 所需要的请求  
![网络请求][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzQwMDY1Nzc2_size_16_color_FFFFFF_t_70 3]  
需要在拦截器，放开请求

package com.zyxx.common.config;
    
    import org.springframework.beans.factory.annotation.Autowired;
    import org.springframework.context.annotation.Configuration;
    import org.springframework.web.servlet.config.annotation.InterceptorRegistration;
    import org.springframework.web.servlet.config.annotation.InterceptorRegistry;
    import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;
    
    import java.util.ArrayList;
    import java.util.List;
    
    /** * 注册拦截器 * * @Author Lizhou **/
    @Configuration
    public class WebConfigurer implements WebMvcConfigurer { 
    
        @Autowired
        private LoginInterceptor loginHandlerInterceptor;
    
        @Override
        public void addInterceptors(InterceptorRegistry registry) { 
            InterceptorRegistration ir = registry.addInterceptor(loginHandlerInterceptor);
            // 拦截路径
            ir.addPathPatterns("/*");
            // 不拦截路径
            List<String> irs = new ArrayList<String>();
            irs.add("/login");
            irs.add("/api/*");
            // 开放knife4j
            irs.add("/doc.html");
            irs.add("/service-worker.js");
            irs.add("/swagger-resources");
            ir.excludePathPatterns(irs);
        }
    }

## 四、使用 ##

使用注解的方式与 swagger2 是一样的

### 1、controller ###

import com.zyxx.common.utils.ResponseResult;
    import com.zyxx.sbm.service.MgtUserService;
    import io.swagger.annotations.Api;
    import io.swagger.annotations.ApiImplicitParam;
    import io.swagger.annotations.ApiImplicitParams;
    import io.swagger.annotations.ApiOperation;
    import org.springframework.beans.factory.annotation.Autowired;
    import org.springframework.stereotype.Controller;
    import org.springframework.web.bind.annotation.GetMapping;
    import org.springframework.web.bind.annotation.RequestMapping;
    import org.springframework.web.bind.annotation.ResponseBody;
    
    /** * <p> * 用户信息表 前端控制器 * </p> * * @author lizhou * @since 2020-06-30 */
    @Api(tags = "后台管理端--用户模块")
    @Controller
    @RequestMapping("/mgt-user")
    public class MgtUserController { 
    
        @Autowired
        private MgtUserService mgtUserService;
    
        @ApiOperation(value = "分页查询用户数据", notes = "分页查询用户数据")
        @ApiImplicitParams({ 
                @ApiImplicitParam(name = "page", value = "页码数", required = true),
                @ApiImplicitParam(name = "limit", value = "每页条数", required = true)
        })
        @GetMapping("list")
        @ResponseBody
        public ResponseResult listUser(int page, int limit) { 
            return mgtUserService.listUser(page, limit);
        }
    }

@Api，整个类的注释  
@ApiOperation，方法上的注释  
@ApiImplicitParams，参数列表的注释  
@ApiImplicitParam，每一个参数的注释

### 2、实体类 ###

import com.baomidou.mybatisplus.annotation.IdType;
    import com.baomidou.mybatisplus.extension.activerecord.Model;
    import com.baomidou.mybatisplus.annotation.TableId;
    import java.io.Serializable;
    
    import io.swagger.annotations.ApiModel;
    import io.swagger.annotations.ApiModelProperty;
    import lombok.Data;
    import lombok.EqualsAndHashCode;
    import lombok.experimental.Accessors;
    
    /** * <p> * 用户信息表 * </p> * * @author lizhou * @since 2020-06-30 */
    @Data
    @EqualsAndHashCode(callSuper = false)
    @Accessors(chain = true)
    @ApiModel(value="mgt_user对象", description="用户信息对象")
    public class MgtUser extends Model<MgtUser> { 
    
        private static final long serialVersionUID = 1L;
    
        @TableId(value = "id", type = IdType.AUTO)
        @ApiModelProperty(value = "主键ID")
        private Long id;
    
        @ApiModelProperty(value = "姓名")
        private String name;
    
        @ApiModelProperty(value = "年龄")
        private Integer age;
    
        @ApiModelProperty(value = "技能")
        private String skill;
    
        @ApiModelProperty(value = "评价")
        private String evaluate;
    
        @ApiModelProperty(value = "分数")
        private Long fraction;
    
        @Override
        protected Serializable pkVal() { 
            return this.id;
        }
    }

@ApiModel，实体类的注解  
@ApiModelProperty，字段的注解

## 五、分组展示 ##

我们针对多个包内的 API 接口，可以选择分组展示，配置如下：

package com.asurplus.common.knife4j;
    
    import com.asurplus.common.consts.SystemConst;
    import org.springframework.beans.factory.annotation.Value;
    import org.springframework.context.annotation.Bean;
    import org.springframework.context.annotation.Configuration;
    import springfox.documentation.builders.ApiInfoBuilder;
    import springfox.documentation.builders.PathSelectors;
    import springfox.documentation.builders.RequestHandlerSelectors;
    import springfox.documentation.service.ApiInfo;
    import springfox.documentation.service.Contact;
    import springfox.documentation.spi.DocumentationType;
    import springfox.documentation.spring.web.plugins.Docket;
    import springfox.documentation.swagger2.annotations.EnableSwagger2;
    
    /**
     * swagger2 配置
     *
     * @Author Lizhou
     */
    @Configuration
    @EnableSwagger2
    public class Knife4jConfig {
    
        /**
         * 是否开启swagger
         */
        @Value("${knife4j.enabled}")
        private boolean enabled;
    
        @Bean("appApi")
        public Docket appApi() {
            return new Docket(DocumentationType.SWAGGER_2)
                    // 是否开启
                    .enable(enabled)
                    // 分组名称
                    .groupName("APP端API文档")
                    .apiInfo(apiInfo())
                    .select()
                    // 扫描包位置，扫描所有带有此注解的方法
                    .apis(RequestHandlerSelectors.basePackage("com.asurplus.api"))
                    .paths(PathSelectors.any())
                    .build();
        }
    
        @Bean("adminApi")
        public Docket adminApi() {
            return new Docket(DocumentationType.SWAGGER_2)
                    // 是否开启
                    .enable(enabled)
                    // 分组名称
                    .groupName("管理端API文档")
                    .apiInfo(apiInfo())
                    .select()
                    // 扫描包位置，扫描所有带有此注解的方法
                    .apis(RequestHandlerSelectors.basePackage("com.asurplus.system"))
                    .paths(PathSelectors.any())
                    .build();
        }
    
        private ApiInfo apiInfo() {
            return new ApiInfoBuilder()
                    // 标题
                    .title(SystemConst.SYSTEM_ITEM_NAME + "管理后台服务API接口文档")
                    // 简介
                    .description("使用 knife4j 搭建的后台服务API在线接口文档")
                    // 服务条款url
                    .termsOfServiceUrl("无")
                    // 版本
                    .version("1.0.0")
                    // 作者
                    .contact(new Contact("Administrators", "无", "无"))
                    // 构建
                    .build();
        }
    }

其中 .enable() 表示开启还是不开启，当我们线上环境的时候，需要关闭在线文档，增加系统安全性

以上就是，SpringBoot中整合 knife4j 接口文档的全部过程

如您在阅读中发现不足，欢迎留言！！！

[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzQwMDY1Nzc2_size_16_color_FFFFFF_t_70]: https://img-blog.csdnimg.cn/20200702143319964.png?x-oss-process=image/watermark,type_ZmFuZ3poZW5naGVpdGk,shadow_10,text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzQwMDY1Nzc2,size_16,color_FFFFFF,t_70
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzQwMDY1Nzc2_size_16_color_FFFFFF_t_70 1]: https://img-blog.csdnimg.cn/20200702143404381.png?x-oss-process=image/watermark,type_ZmFuZ3poZW5naGVpdGk,shadow_10,text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzQwMDY1Nzc2,size_16,color_FFFFFF,t_70
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzQwMDY1Nzc2_size_16_color_FFFFFF_t_70 2]: https://img-blog.csdnimg.cn/2020070214342733.png?x-oss-process=image/watermark,type_ZmFuZ3poZW5naGVpdGk,shadow_10,text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzQwMDY1Nzc2,size_16,color_FFFFFF,t_70
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzQwMDY1Nzc2_size_16_color_FFFFFF_t_70 3]: https://img-blog.csdnimg.cn/20200702144338302.png?x-oss-process=image/watermark,type_ZmFuZ3poZW5naGVpdGk,shadow_10,text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzQwMDY1Nzc2,size_16,color_FFFFFF,t_70