Springboot整合knife4j

本文介绍knife4j的用法，如何整合到springboot项目中

文章目录

前言

参考文档：

• 官方文档
• 版本问题
• 文档注解

在项目开发中，自测和联调时，一篇详细通用的接口文档显得尤为重要，不仅提高了开发效率，而且避免了无效沟通，保证了流程的规范性。
Knife4j跟Swagger用法基本一样，UI界面设计更加漂亮可用。

环境搭建

版本对应关系：

application.yml文件配置：
Springfox 使用的路径匹配是基于AntPathMatcher的，而Spring Boot 2.6.X使用的是PathPatternMatcher，因此需要配置pathmatch。

server:
  port:9203

spring:
  application:
    name: learn-api
  mvc:
    pathmatch:
      matching-strategy: ant_path_matcher 

引入依赖：

<!--版本--><knife4j.version>3.0.3</knife4j.version><dependency><groupId>com.github.xiaoymin</groupId><artifactId>knife4j-spring-boot-starter</artifactId><version>${knife4j.version}</version></dependency><dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-actuator</artifactId></dependency>

基本配置

文档基础信息

/**
 * @Author: Yangmiao
 * @Date: 2023/4/18 10:03
 * @Desc: 文档基础信息
 */@Data@Builder@ToStringpublicclassKnife4jProperties{/**
     * API文档生成基础路径
     */privateString apiBasePackage;/**
     * 是否要启用登录认证
     */privateboolean enableSecurity;/**
     * 文档标题
     */privateString title;/**
     * 文档描述
     */privateString description;/**
     * 文档版本
     */privateString version;/**
     * 文档联系人姓名
     */privateString contactName;/**
     * 文档联系人网址
     */privateString contactUrl;/**
     * 文档联系人邮箱
     */privateString contactEmail;}

将Knife4j基础配置抽取成抽象类，对于Properties参数单独配置

/**
 * @Author: Yangmiao
 * @Date: 2023/4/18 10:00
 * @Desc:
 */publicabstractclassBaseKnife4jConfig{@BeanpublicDocketdocket(){Knife4jProperties properties =swaggerProperties();Docket docket =newDocket(DocumentationType.OAS_30).apiInfo(apiInfo(properties)).select().apis(RequestHandlerSelectors.basePackage(properties.getApiBasePackage())).paths(PathSelectors.any()).build();return docket;}privateApiInfoapiInfo(Knife4jProperties swaggerProperties){returnnewApiInfoBuilder().title(swaggerProperties.getTitle()).description(swaggerProperties.getDescription()).contact(newContact(swaggerProperties.getContactName(), swaggerProperties.getContactUrl(), swaggerProperties.getContactEmail())).version(swaggerProperties.getVersion()).build();}/**
     *
     * 增加如下配置可解决Spring Boot 6.x 与Swagger 3.0.0 不兼容问题
     * @param webEndpointsSupplier
     * @param servletEndpointsSupplier
     * @param controllerEndpointsSupplier
     * @param endpointMediaTypes
     * @param corsProperties
     * @param webEndpointProperties
     * @param environment
     * @return
     */@BeanpublicWebMvcEndpointHandlerMappinghandlerMapping(WebEndpointsSupplier webEndpointsSupplier,ServletEndpointsSupplier servletEndpointsSupplier,ControllerEndpointsSupplier controllerEndpointsSupplier,EndpointMediaTypes endpointMediaTypes,CorsEndpointProperties corsProperties,WebEndpointProperties webEndpointProperties,Environment environment){List<ExposableEndpoint<?>> allEndpoints =newArrayList();Collection<ExposableWebEndpoint> webEndpoints = webEndpointsSupplier.getEndpoints();
        allEndpoints.addAll(webEndpoints);
        allEndpoints.addAll(servletEndpointsSupplier.getEndpoints());
        allEndpoints.addAll(controllerEndpointsSupplier.getEndpoints());String basePath = webEndpointProperties.getBasePath();EndpointMapping endpointMapping =newEndpointMapping(basePath);boolean shouldRegisterLinksMapping =this.shouldRegisterLinksMapping(webEndpointProperties, environment, basePath);returnnewWebMvcEndpointHandlerMapping(endpointMapping, webEndpoints, endpointMediaTypes, corsProperties.toCorsConfiguration(),newEndpointLinksResolver(allEndpoints, basePath), shouldRegisterLinksMapping,null);}privatebooleanshouldRegisterLinksMapping(WebEndpointProperties webEndpointProperties,Environment environment,String basePath){return webEndpointProperties.getDiscovery().isEnabled()&&(StringUtils.hasText(basePath)||ManagementPortType.get(environment).equals(ManagementPortType.DIFFERENT));}/**
     * 自定义Swagger配置
     */publicabstractKnife4jPropertiesknife4jProperties();}

继承BaseKnife4jConfig，单独实现knife4jProperties函数，自定义属性值，这样设计的优点：

1. 在微服务开发中，每个微服务都有接口函数，将knife4j抽取成一个单独的公共module，上层直接引入后，自定义属性值。

/**
 * @Author: Yangmiao
 * @Date: 2023/4/18 10:27
 * @Desc: knife4j配置
 */@Configuration@EnableOpenApipublicclassKnife4jConfigextendsBaseKnife4jConfig{@OverridepublicKnife4jPropertiesknife4jProperties(){returnKnife4jProperties.builder().apiBasePackage("com.ym.learn.api").title("Api接口文档").description("Api接口文档").contactName("ym").version("1.0").enableSecurity(false).build();}}

常用注解

@Api    用在请求的类上表示对类(controller类)的说明。tags=“说明该类的作用，可以在UI界面上看到的注解”，value=“该参数没什么意义，在UI界面上也看到，所以不需要配置”
@ApiOperation    用在请求的方法(controller类的方法)上说明方法的用途和作用。value=“说明方法的用途、作用”，notes=“方法的备注说明”
@ApiModel    用于响应类(javaBean类)上表示一个返回响应数据的信息
@ApiModelProperty    用在属性上，描述响应类的属性(javaBean类的方法或属性)@ApiImplicitParams    用在请求的方法(controller类的方法)上，表示一组参数说明
@ApiImplicitParam    用在@ApiImplicitParams注解中，指定一个请求参数的各个方面
@ApiResponses    用在请求的方法(controller类的方法)上，表示一组响应
@ApiResponse    用在@ApiResponses注解中，用于表达一个的响应信息
@ApiIgnore    用于类或者方法(controller类的方法或controller类)上，可以不被swagger显示在页面上
@ApiParam    作用在参数、方法和字段(cotroller类的方法参数)上，类似@ApiImplicitParam

    个别注解详解：
    ①其中@ApiParam和@ApiImplicitParam的功能是相同的，但是@ApiImplicitParam的适用范围更广

@ApiImplicitParam：用在 @ApiImplicitParams 注解中，指定一个请求参数的配置信息       
    name：参数名
    value：参数的汉字说明、解释
    required：参数是否必须传
    paramType：参数放在哪个地方
        · header --> 请求参数的获取：@RequestHeader
        · query --> 请求参数的获取：@RequestParam
        · path（用于restful接口）--> 请求参数的获取：@PathVariable
        · body（不常用）
        · form（不常用）    
    dataType：参数类型，默认String，其它值dataType="Integer"       
    defaultValue：参数的默认值

@ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息
    code：数字，例如400
    message：信息，例如"请求参数没填好"
    response：抛出异常的类

@ApiParam    作用在参数、方法和字段上
    name：参数名称，参数名称将从 filed/method/parameter 名称中派生，但你可以覆盖它，路径参数必须始终命名为它们所代表的路径部分
    value：参数简单描述
    defaultValu：描述参数默认值
    allowableValues：可接收参数值限制，有三种方式,取值列表，取值范围
    required：是否为必传参数,false:非必传;true:必传
    access：参数过滤，请参阅:io.swagger.core.filter.SwaggerSpecFilter
    allowMultiple：指定参数是否可以通过多次出现来接收多个值
    hidden：隐藏参数列表中的参数
    example：非请求体(body)类型的单个参数示例
    example：参数示例，仅适用于请求体类型的请求
    type：添加覆盖检测到类型的功能
    format：添加提供自定义format格式的功能
    allowEmptyValue：添加将格式设置为空的功能
    readOnly：添加被指定为只读的能力
    collectionFormat：添加使用 array 类型覆盖 collectionFormat 的功能

/**
 * @Author: Yangmiao
 * @Date: 2023/4/9 22:45
 * @Desc:
 */@RestController@Api(tags ="hello测试接口")publicclassHelloController{@ApiOperation(value ="hello测试")@GetMapping("/hello")publicStringhello(){return"Hello World.";}@AutowiredprivateLoginUserHolder loginUserHolder;@GetMapping("/currentUser")publicUserDTOcurrentUser(){return loginUserHolder.getCurrentUser();}}

测试

访问

http://localhost:9203/doc.html