技术总结

• 如果你追求现代化、国际化标准，推荐使用 Springdoc OpenAPI。
• 如果你希望减少代码侵入性、注重中文文档体验，推荐使用 Smart-Doc。
• 如果你在国内项目中需要更友好的 UI 和功能，可尝试 Knife4j。

Springdoc OpenAPI

官网：https://springdoc.org

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
    <version>1.6.14</version>
</dependency>

http://localhost:8080/swagger-ui.html
或
http://localhost:8080/swagger-ui/index.html

Swagger + Springfox（已逐渐淘汰）

已不再积极维护

Smart-Doc（国产优秀工具）

官网：https://smart-doc-group.gitee.io/smart-doc-website/

不依赖注解，通过分析 Java 注释生成文档，不依赖Swagger

<plugin>
    <groupId>com.power.doc</groupId>
    <artifactId>smart-doc-maven-plugin</artifactId>
    <version>3.2.0</version>
    <executions>
        <execution>
            <phase>generate-sources</phase>
            <goals>
                <goal>html</goal>
            </goals>
        </execution>
    </executions>
</plugin>

YApi + 自动生成对接

• YApi 是一个开源的接口管理平台
• 可以通过插件将 Spring Boot 接口自动导入到 YApi 平台中
• 支持 CI/CD 流程自动化同步接口信息

Knife4j

官网：https://doc.xiaominfo.com/

是对 swagger-bootstrap-ui 的升级版本

<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-spring-boot-starter</artifactId>
    <version>3.0.3</version>
</dependency>

http://localhost:8080/doc.html

swagger说明

• Swagger 是一个接口定义与文档生成的标准体系，它为 RESTful API 提供了一套规范化的描述方式（即 OpenAPI Specification，简称 OAS），并配套了一系列工具链来支持文档自动生成、可视化展示、接口测试等能力。
• Swagger 最初是由 SmartBear 公司提出的一套 API 描述规范和工具集。
• 后来该规范被标准化为 OpenAPI Specification（OAS），成为行业标准。
• 因此，Swagger 可以看作是 OpenAPI 规范的一个具体实现。

Spring Boot 中常用的 Swagger 实现框架：

• Springfox：基于 Swagger 2 规范，已不再维护，不支持 Spring Boot 2.6+ 和 OpenAPI 3.0
• Springdoc OpenAPI：基于 OpenAPI 3.0 规范，支持 Swagger UI、ReDoc 等界面展示，Springdoc 是目前推荐替代 Springfox 的主流方案
• Knife4j：基于 Swagger UI，对 Swagger UI 的增强版，UI 更美观，功能更丰富

OpenAPI Specification (OAS)
       ↑
       └── Swagger（原始实现）
               ├── Swagger UI
               ├── Swagger Core
               └── Swagger Codegen
       └── Springdoc OpenAPI（现代实现）
               ├── 支持 OpenAPI 3.0
               └── 集成 Swagger UI 展示
       └── Knife4j（国产增强版）
               ├── 基于 Swagger UI
               └── 支持 Spring Boot