Swagger升级指南：从注解到实战

一、Swagger 注解的变化：从 @Api 到 @Operation

1. 旧版本（Swagger 2.0 + Springfox）

• 核心注解：
  • @Api: 标记 Controller 类，定义接口分组。
  • @ApiOperation: 标记 Controller 方法，定义接口功能。

  @Api(tags = "用户管理")
  @RestController
  public class UserController {
      @ApiOperation("创建用户")
      @PostMapping("/users")
      public User createUser(@RequestBody User user) { ... }
  }
  

• 依赖库：springfox-swagger2 + springfox-swagger-ui。
• 问题：随着 OpenAPI 规范升级，Springfox 逐渐停止维护，兼容性较差。

2. 新版本（OpenAPI 3.0 + SpringDoc）

• 核心注解：
  • @Tag: 替代 @Api，标记接口分组。
  • @Operation: 替代 @ApiOperation，标记方法功能。

  @Tag(name = "用户管理")
  @RestController
  public class UserController {
      @Operation(summary = "创建用户")
      @PostMapping("/users")
      public User createUser(@RequestBody User user) { ... }
  }
  

• 依赖库：springdoc-openapi-starter-webmvc-ui。
• 优势：支持 OpenAPI 3.0 规范，兼容 Spring Boot 3+，维护活跃。
  在使用的时候发现要与时俱进。

---

二、Swagger 的核心概念

1. Swagger 是什么？

• 定义：Swagger 是一套围绕 OpenAPI 规范（OAS）构建的工具链，用于设计、构建、文档化和测试 RESTful API。
• 核心功能：
  • 设计：通过 YAML/JSON 定义 API 结构。
  • 文档生成：自动生成可视化 API 文档。
  • 代码生成：根据 API 规范生成客户端/服务端代码。
  • 测试：直接在浏览器中调试接口。

2. Swagger 工具链

工具	用途
Swagger Editor	在线编辑器，用于编写 OpenAPI 规范（YAML/JSON）。
Swagger UI	自动生成可视化 API 文档，支持接口调试（如图形化请求发送）。
Swagger Codegen	根据 OpenAPI 规范生成客户端（如 Java、Python）和服务端框架代码。
Swagger Hub	云端平台，支持团队协作设计和管理 API。

---

三、Swagger 的衍生知识

1. OpenAPI 规范（原 Swagger 规范）

• 历史：Swagger 规范于 2015 年捐赠给 Linux 基金会，并重命名为 OpenAPI 规范（OAS）。
• 版本：
  • Swagger 2.0：最后一个由 Swagger 团队维护的版本。
  • OpenAPI 3.0/3.1：当前主流版本，支持更丰富的 API 描述能力（如 Webhooks、多服务器配置）。

2. Springfox vs SpringDoc

特性	Springfox	SpringDoc
支持规范	OpenAPI 2.0 (Swagger 2.0)	OpenAPI 3.0/3.1
维护状态	已停止更新	活跃维护
注解风格	@Api、@ApiOperation	@Tag、@Operation
Spring Boot 3	不兼容	兼容

3. 其他 API 文档工具

工具	特点
Redoc	专注于文档渲染，支持 OpenAPI 规范，生成静态 HTML 页面。
RAML	基于 YAML 的 API 描述语言，强调设计优先。
API Blueprint	使用 Markdown 格式编写 API 文档，适合简单场景。
Postman	支持 API 测试、文档生成和协作，但非开源。

---

四、Swagger 的典型应用场景

1. API 设计：团队协作定义接口规范（使用 Swagger Editor）。
2. 文档自动化：通过代码注解生成实时更新的 API 文档。
3. 前后端协作：前端开发者直接通过 Swagger UI 查看和调试接口。
4. 代码生成：生成客户端 SDK 或服务端框架代码（如 Spring Boot）。

---

五、快速上手 SpringDoc (OpenAPI 3.0)

1. 添加依赖

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

2. 配置注解

@Tag(name = "用户管理", description = "用户注册、登录、信息管理")
@RestController
public class UserController {
    @Operation(summary = "创建用户", description = "通过用户名和密码注册新用户")
    @PostMapping("/users")
    public User createUser(@RequestBody User user) { ... }
}

3. 访问文档

• OpenAPI JSON：http://localhost:8080/v3/api-docs
• Swagger UI：http://localhost:8080/swagger-ui.html

---

六、总结

• 注解变化：@Api → @Tag、@ApiOperation → @Operation 是 Swagger 向 OpenAPI 规范升级的结果，建议使用 SpringDoc + OpenAPI 3.0。
• Swagger 生态：涵盖设计、文档、测试全流程，是 RESTful API 开发的事实标准。
• 替代方案：根据需求选择 Redoc、Postman 等工具，但 OpenAPI 规范仍是行业主流。