Sping Boot3整合knife4j接口文档_springboot3整合knife4j

本篇文章主要介绍如何在springboot3中整合knife4j。

注：springboot3系列示例代码采用3.2.2版本，jdk版本使用17

一、什么是接口文档

接口文档就是写接口信息的文档，每条接口包括：

• 请求参数
• 响应参数
• 接口地址
• 接口名称
• 请求类型
• 请求格式
• 备注

二、谁用

一般是后端或者负责人来提供，后端和前端都要使用

三、为什么需要接口文档

• 有个书面内容（背书或者归档），便于大家参考和查阅，便于沉淀和维护，拒绝口口相传
• 接口文档便于前端和后端开发对接，前后端联调的介质，后端=>接口文档<=前端
• 好的接口文档支持在线调试，在线测试，可以作为工具提高我们的开发测试效率

四、怎么做好接口文档

• 手写（比如腾讯文档、Markdown笔记）
• 自动化接口文档生成：自动根据项目生成完整的文档或在线调试的网页。例如：Swagger、Postman(侧重接口管理)（国外）；apifox、apipost、eolink(国产)

五、什么是knife4j

knife4j是一个集Swagger2 和 OpenAPI3为一体的增强解决方案，帮助开发者快速聚合使用OpenAPI规范，快速生成API文档，并且提供一些额外的功能，比如:

1. API文档生成：可以根据Controller和方法上的注解自动生成Markdown格式的API文档
2. 在线访问API：可以在knife4j的页面直接访问我们的API接口
3. Token管理：可以在knife4j中对API Token进行管理
4. 比较请求与响应：可以比较同一个API的请求与响应内容的差异
5. 高亮API响应：将API响应中的JSON高亮显示，方便查看
6. ..

六、集成knife4j

引入pom依赖（pom.xml）

 <!--引入knif4j-->
    <dependency>
      <groupId>com.github.xiaoymin</groupId>
      <artifactId>knife4j-openapi3-jakarta-spring-boot-starter</artifactId>
      <version>4.4.0</version>
    </dependency>

配置文件(application.yml文件)

# springdoc-openapi项目配置，访问地址：http://127.0.0.1:8080/doc.html
springdoc:
  swagger-ui:
    path: /swagger-ui.html
    tags-sorter: alpha
    operations-sorter: alpha
  api-docs:
    path: /v3/api-docs
  group-configs:
    - group: 'default'
      paths-to-match: '/**'
      packages-to-scan: com.example.backend
 
# knife4j的增强配置，不需要增强可以不配
knife4j:
  enable: true
  setting:
    language: zh_cn

 application.yml文件下全部配置

spring:
  profiles:
    active: dev
  application:
    name: parentMaching
  #session 失效时间
  session:
    timeout: 86400
server:
  port: 8080
  servlet:
    context-path: /api
mybatis-plus:
  configuration:
    map-underscore-to-camel-case: false
    log-impl: org.apache.ibatis.logging.stdout.StdOutImpl
  global-config:
    db-config:
      logic-delete-field: isDelete # 全局逻辑删除的实体字段名(since 3.3.0,配置后可以忽略不配置步骤2)
      logic-delete-value: 1 # 逻辑已删除值(默认为 1)
      logic-not-delete-value: 0 # 逻辑未删除值(默认为 0)
# springdoc-openapi项目配置，访问地址：http://127.0.0.1:8080/doc.html
springdoc:
  swagger-ui:
    path: /swagger-ui.html
    tags-sorter: alpha
    operations-sorter: alpha
  api-docs:
    path: /v3/api-docs
  group-configs:
    - group: 'default'
      paths-to-match: '/**'
      packages-to-scan: com.example.backend
 
# knife4j的增强配置，不需要增强可以不配
knife4j:
  enable: true
  setting:
    language: zh_cn

swagger初始化配置（在config目录下配置文件）

package com.example.backend.config;
 
import io.swagger.v3.oas.models.ExternalDocumentation;
import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Contact;
import io.swagger.v3.oas.models.info.Info;
import io.swagger.v3.oas.models.info.License;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
 
 
/**
 * 自定义 Swagger 接口文档的配置
 * @author wang
 */
@Configuration
public class SwaggerConfig {
 
    @Bean
    public OpenAPI springShopOpenAPI() {
        return new OpenAPI()
                .info(new Info().title("伙伴匹配系统")
                        .description("伙伴匹配系统API文档")
                        .version("v1")
                        .license(new License().name("Apache 2.0").url("http://springdoc.org")))
                        .externalDocs(new ExternalDocumentation()
                        .description("外部文档")
                        .url("https://springshop.wiki.github.org/docs"));
    }
 
}

最后访问地址：http://127.0.0.1:8080/api/doc.html