1. 介绍

Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务(https://swagger.io/)。 它的主要作用是：

1. 使得前后端分离开发更加方便，有利于团队协作

2. 接口的文档在线自动生成，降低后端开发人员编写接口文档的负担

3. 功能测试

   Spring已经将Swagger纳入自身的标准，建立了Spring-swagger项目，现在叫Springfox。通过在项目中引入Springfox ，即可非常简单快捷的使用Swagger。

knife4j是为Java MVC框架集成Swagger生成Api文档的增强解决方案,前身是swagger-bootstrap-ui,取名kni4j是希望它能像一把匕首一样小巧,轻量,并且功能强悍!

目前，一般都使用knife4j框架。

2. 使用步骤

备注：项目使用的spring boot版本是2.7.18，java版本是17。

使用不同版本，可能配置方法有所不同。

2.1 导入 knife4j 的maven坐标

在pom.xml中添加依赖：

        <!-- Knife4j 的起步依赖，用于增强 Swagger 文档生成工具，便于接口文档管理 -->
        <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>knife4j-openapi2-spring-boot-starter</artifactId>
            <version>${knife4j}</version>
        </dependency>

2.2 yml文件中进行相关配置

knife4j:
  enable: true # 开启或禁用 Knife4j 文档功能。true 表示启用，false 表示禁用。
  openapi:
    title: 标题 # 定义 API 文档的标题，可以自定义为 "项目 API 文档"。
    description: "描述" # API 文档的简短描述，帮助用户了解项目背景。
    email: "" # API 维护者的联系邮箱，可为空或填入负责人的邮箱地址。
    concat: cyt # API 文档的联系人名称，定义为 'cyt'，可替换为实际联系人名字。
    url:  # 项目文档的链接，可以指向官方文档、帮助文档等。
    version: v1.0 # API 的版本号，这里设置为 v4.0，可根据项目实际版本调整。
    license: Apache 2.0 # 使用的开源协议类型，这里为 Apache 2.0 协议。
    license-url:  # 开源协议的链接地址，指向协议的详细内容。
    terms-of-service-url:  # 服务条款的链接，可以引导用户查看服务条款。
    
    group:
      # 定义 API 文档的第一个分组
      test1:
        group-name: 管理端 # 组名称为 "管理端"，在 Knife4j 界面中显示。
        api-rule: package # API 显示规则为按包名筛选和归类。
        api-rule-resources:
          - com.cyt.controller.admin # 此组下的 API 来自于 com.cyt.controller.admin 包。

      # 定义 API 文档的第二个分组
      test2:
        group-name: 用户端 # 组名称为 "用户端"，在 Knife4j 界面中显示。
        api-rule: package # API 显示规则为按包名筛选和归类。
        api-rule-resources:
          - com.cyt.controller.user # 此组下的 API 来自于 com.cyt.controller.user 包。

3. 扩展配置

除了上述已经列出的 knife4j 配置项，knife4j 还支持许多其他常用的配置项，以便进一步定制化接口文档生成。以下是一些常见的 knife4j 配置项及其用途：

3.1 paths

• 用于控制哪些路径的 API 会被生成文档。
• 支持配置扫描的 API 路径，以更细粒度地控制文档输出。

knife4j:
  openapi:
    paths:
      include: # 包含的 API 路径
        - /api/v1/**
      exclude: # 排除的 API 路径
        - /api/admin/**

3.2 header

• 配置全局的 HTTP 请求头，比如一些项目中的通用认证 token、traceId 等，可以在测试页面中全局配置。

knife4j:
  openapi:
    header:
      name: Authorization # 请求头的名称
      description: "用于认证的 token" # 描述
      defaultValue: "Bearer token" # 默认值

3.3 server

• 配置文档中默认的服务器地址，可以是多个服务器，用于测试和调试 API。

knife4j:
  openapi:
    server:
      url: http://localhost:8080 # 服务器地址
      description: 本地开发环境

3.4 basic-auth

• 用于配置基础认证的用户和密码，控制访问文档的权限。

knife4j:
  basic-auth:
    enable: true # 是否启用基础认证
    username: admin # 登录用户名
    password: 123456 # 登录密码

3.5 response-message

• 自定义全局的响应消息，用于规范所有接口的返回消息格式。

knife4j:
  openapi:
    response-message:
      - code: 400
        message: "Bad Request"
      - code: 500
        message: "Internal Server Error"

3.6 tag-order

• 配置接口文档中 Tag 的显示顺序，按业务模块分组。

knife4j:
  openapi:
    tag-order: # 自定义 Tag 的顺序
      - 用户管理
      - 订单管理
      - 商品管理

3.7 markdown

• 支持在文档中插入自定义的 Markdown 内容，可以用来添加额外的文档说明或项目介绍。

knife4j:
  openapi:
    markdown:
      enable: true # 启用 markdown
      content: | # 支持多行 markdown 内容
        ## 项目说明
        本接口文档是针对苍穹外卖项目开发的 API 说明文档。

3.8 enable-security

• 是否启用全局的 API 安全认证配置，比如通过 OAuth2、JWT 等方式。

knife4j:
  openapi:
    enable-security: true # 启用全局安全认证
    oauth2:
      token-url: /oauth/token # OAuth2 的 token 获取地址
      scopes:
        read: 允许读取数据
        write: 允许写入数据

3.9 docket

• 更为细粒度地自定义文档生成规则，覆盖默认的文档行为。例如可以用 docket 来生成不同分组的接口文档。

knife4j:
  openapi:
    docket:
      groupName: "用户模块" # 自定义文档分组名
      basePackage: "com.cyt.controller.user" # 定义扫描的包
      paths:
        include: /user/**

3.10 license 和 license-url

• 自定义开源许可证信息，定义项目的许可证和许可证链接地址，便于访问者查看具体的开源协议。

knife4j:
  openapi:
    license: "MIT License"
    license-url: "https://opensource.org/licenses/MIT"

3.11 contact

• 配置联系信息，提供接口文档的联系人信息，便于使用者找到项目维护者。

knife4j:
  openapi:
    contact:
      name: "开发者姓名"
      url: "https://developer.example.com"
      email: "developer@example.com"

3.12 external-docs

• 配置额外的外部文档链接，帮助开发者跳转到项目的外部文档页面，进行更详细的了解。

knife4j:
  openapi:
    external-docs:
      description: "查看更多项目文档"
      url: "https://example.com/docs"

3.13 model-convert

• 配置实体模型（Model）转换时的一些策略和设置，控制实体类在文档中如何展现。

knife4j:
  openapi:
    model-convert:
      enable: true # 是否启用模型转换
      include-enums: true # 是否包括枚举类

4. 总结

使用场景总结：

• 基础配置（如 title、description、version）用于项目基本信息的定义。
• 分组配置（如 group）用于将 API 分为不同的模块或组别，便于管理和查看。
• 路径控制（如 paths）用于指定哪些 API 路径会被生成文档。
• 请求头与认证（如 header、basic-auth）方便为全局设置认证 token 和用户登录信息。
• 响应消息（如 response-message）为全局的返回码与消息做统一配置。
• 文档安全性（如 enable-security）允许为文档访问增加 OAuth2 或 JWT 的认证。