API 文档是项目开发实践中极其重要的一个环节。借助接口文档，前端与后端，服务与服务，接口的结构和功能一目了然，交流成本显著降低。

市面上有很多 HTTP API 文档管理工具，但最便捷的应该是 Swagger。不但能管理接口，还提供了测试接口的功能；纯 Web 页面，无需打开客户端。就个人体验而言，Swagger 可以显著提高开发效率。

本文将按照从概念到实践的方式，讨论如何用 Swagger 来管理 Spring Boot 项目中的 HTTP API。

Swagger？OpenAPI？

一直以来，关于 Swagger 的许多名词都让我困惑。Swagger 是什么？跟 Swagger UI 是什么关系？OpenAPI 又是什么？什么 Springfox Springdoc，这些又是什么？即使不明白，也不影响基本使用，偶尔会在扩展功能时有些问题，通过搜索引擎也很容易找到解决方案。但如果厘清了这些概念，就可以从更深层次理解 Swagger 的结构，从而减少使用时的困惑。

首先，Swagger 是一个专注 API 文档管理的项目，核心是 Swagger 规范。Swagger 规范定义了 HTTP API 的结构化表示形式，包括 API 路径、参数、响应结构、名称、备注等方方面面。简单来说，有了 Swagger 规范，我们就可以用 JSON 和 YAML 来表示 API。

Swagger 规范经历了两个大版本，1.0 和 2.0。到 3.0 时，改名为 OpenAPI 这个更标准化的名称。所以 OpenAPI 实际上就是新版的 Swagger 规范。我们可能会看到 OpenAPI 3.0 的写法，这并不意味着 OpenAPI 有三个版本，而是指 OpenAPI 的第一个版本就是 3.0。需要注意的是，OpenAPI 修改了一些内部名词，与 Swagger 2.0 不兼容。因此 OpenAPI 不支持使用 Swagger 2.0 的老项目。

基于接口定义规范，Swagger 项目提供了一系列工具用于辅助 API 文档管理。

最常用的是 Swagger UI，这是一个前端 Web 页面，用于展示 API 文档，只要数据符合 Swagger 规范，就能正确显示。此外，Swagger UI 还提供了接口测试的功能，在页面上就能调用接口，简单又便捷。我们可以遵循 OpenAPI 规范，直接在 Yaml 文件中定义 API，然后通过接口暴露给 Swagger UI，就能在使用 Swagger UI 显示 API 文档和测试 API。但这不仅繁琐，还容易出错。我们还有更好的选择。

另一个常用的 Swagger 工具是 Swagger Core，这是一个 Java jar 包，提供了 Swagger 规范对应的 Java 对象类，以及相应的注解类。在 Swagger 2.0 中常用的 @Api @ApiModel @ApiOperation 就出自这个包。同时，Swagger Core 也支持最新的 OpenAPI 规范。有了 Swagger Core，就能直接用注解定义 API，从注解中提取 API 文档信息，提供给 Swagger UI，而不是自己手动编写 Yaml 文件，显然更加简单。

Swagger Core 只提供了定义数据的功能，采集接口数据需要额外的库。在 Sping 生态中，可以使用 SpringFox 和 Springdoc。两者功能相近，都支持从根据注解采集 Swagger 接口定义数据，且都是独立开源项目，不隶属于 Swagger 和 Spring 的任何一方。两个库各有限制。 SpringFox 支持 Swagger 2 版本，但已经不再维护，不支持 OpenAPI，也不支持最新的 Spring Boot 3。Springdoc 只支持最新的 OpenAPI 规范，支持所有的 Spring Boot 版本。

Swagger 专注于定义规范（OpenAPI、Swagger Core）和展示数据（Swagger UI），并不负责采集数据。可以通过 Springfox 或 Springdoc 来采集 Swagger 数据。选择的依据是 Spring Boot 的版本和 OpenAPI 的版本。

如果不想用默认的 Swagger UI，GitHub 上有很多第三方 swagger-ui 项目。在 Chrome 浏览器商店，甚至还有一个 Swagger-UI 的扩展，扩展了更换主题的功能。

与 Spring Boot 3 共舞

现在进入实践部分，以 Spring Boot 3 为例，介绍如何使用 Springdoc 来管理 API 文档。

首先，引入 Springdoc 依赖。

<dependency>
    <groupId>org.springdocgroupId>
    <artifactId>springdoc-openapi-starter-webmvc-uiartifactId>
    <version>2.6.0version>
dependency>

这个依赖会同时引入 springdoc-openapi-starter-webmvc-ui 和 springdoc-openapi-starter-webmvc-api 的依赖，前者封装了 Swagger UI，后者用于生成 OpenAPI 数据，内部引用 Swagger Core。

通过引入 springdoc-openapi-starter-webmvc-ui 依赖，提供以下功能：

如果项目使用了 Spring Security，则需要调整配置，不拦截 Swagger 相关的接口，否则 Swagger UI 页面无法正常工作。

@EnableWebSecurity
@Configuration
public class SecurityConfig {
    @Bean
    public SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
        return http.authorizeHttpRequests(auth -> {
                    auth.requestMatchers("/swagger-ui/**", "/v3/api-docs/**").permitAll();
                    auth.anyRequest().authenticated();
                })
                // ... 其他配置
                .build();
    }
}

此时启动项目，就可以通过 :8080/swagger-ui.html 或 :8080/swagger-ui/index.html 访问 Swagger UI 页面，查看 API 文档。

Springdoc 提供了许多配置项，可以对 Swagger UI 进行配置。其中，springdoc.swagger-ui. 前缀的设置用于调整 Swagger UI，其他则是数据相关的配置。

springdoc:
  swagger-ui:
    display-request-duration: true # 显示接口响应时间
    path: doc.html # 修改默认访问路径 swagger-ui.html 为 doc.html
    use-root-path: true # 使用根路径 / 访问 Swagger UI
  group-configs:
    - group: 'default' # 定义一个分组，名称为 default
      paths-to-match: '/**' # 匹配所有接口

启用 use-root-path 后，访问 Swagger UI 的地址为 :8080/，这对于纯后端项目来说，非常方便。