Swagger 教程

以下是目前最流行的 Swagger（现已改名为 OpenAPI）完整教程，适用于初学者到中高级开发者（2025年最新实践）。内容涵盖从零开始使用 Swagger/OpenAPI 3.0/3.1 生成美观、交互式的 API 文档。

1. Swagger 是什么？

• Swagger 是一套围绕 OpenAPI 规范（OpenAPI Specification，简称 OAS）的开源工具集
• 现在官方名称是 OpenAPI，但大家仍然习惯叫 Swagger
• 主要作用：让后端写一次注解/配置，就能自动生成：
• 美观的在线 API 文档（Swagger UI）
• 可交互测试（Swagger UI）
• 客户端 SDK（Java、TypeScript、Go 等几十种语言）
• 服务端骨架代码

主流技术栈对应方案（2025最新）：

语言/框架	推荐工具	版本要求
Spring Boot (Java)	springdoc-openapi + springdoc-openapi-ui	Spring Boot 2.6+ / 3.x
Spring Boot (老项目)	springfox-swagger2 + swagger3 兼容方案	即将彻底淘汰
.NET 6/7/8	Swashbuckle.AspNetCore	官方推荐
Node.js	swagger-jsdoc + swagger-ui-express	最常用
Go	go-swagger 或 swag
Python	FastAPI（自带）或 drf-yasg / drf-spectacular
Kotlin	springdoc-openapi-kotlin

2. 【最推荐】Spring Boot 3 + springdoc-openapi（2025 主流写法）

步骤1：添加依赖（Maven）

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
    <version>2.6.0</version>  <!-- 2025年11月最新版 -->
</dependency>

步骤2：写一个接口示例

@RestController
@RequestMapping("/api/users")
@Tag(name = "用户管理", description = "用户相关的接口")
public class UserController {

    @GetMapping("/{id}")
    @Operation(summary = "根据ID查询用户", description = "返回用户信息详情")
    @ApiResponses secs(
        @ApiResponse(responseCode = "200", description = "成功",
            content = @Content(schema = @Schema(implementation = UserVO.class))),
        @ApiResponse(responseCode = "404", description = "用户不存在")
    ))
    public ResponseEntity<UserVO> getUserById(
            @Parameter(description = "用户ID", required = true) @PathVariable Long id,
            @Parameter(description = "是否包含详细信息") @RequestParam(defaultValue = "false") boolean detail) {

        // 业务代码...
        return ResponseEntity.ok(userService.getById(id));
    }

    @PostMapping
    @Operation(summary = "创建新用户")
    public UserVO createUser(@RequestBody @Valid CreateUserDTO dto) {
        return userService.create(dto);
    }
}

步骤3：可选配置 application.yml

springdoc:
  swagger-ui:
    path: /swagger-ui.html          # 访问地址
    tags-sorter: alpha
    operations-sorter: alpha
  api-docs:
    path: /v3/api-docs              # OpenAPI JSON 地址
  packages-to-scan: com.yourpackage.controller  # 扫描包
  default-consumes-media-type: application/json
  default-produces-media-type: application/json

步骤4：启动项目后访问

• 文档页面：http://localhost:8080/swagger-ui.html
• OpenAPI JSON：http://localhost:8080/v3/api-docs
• OpenAPI YAML：http://localhost:8080/v3/api-docs.yaml

3. 常用注解速查表（springdoc）

注解	作用位置	说明
@Tag	类或方法	分组（原来叫 @Api）
@Operation	方法	接口摘要、描述
@Parameter	参数	参数说明
@Schema	实体类/DTO字段	字段说明、示例值、是否必填等
@ApiResponse	方法	返回码说明
@ApiResponses	方法	多个 @ApiResponse 包装
@RequestBody	参数	标记请求体
@Hidden	类/方法/字段	隐藏不显示在文档中

DTO 示例：

@Schema(description = "创建用户请求体")
public record CreateUserDTO(
    @Schema(description = "用户名", example = "zhangshan", requiredMode = Schema.RequiredMode.REQUIRED)
    String username,

    @Schema(description = "邮箱", format = "email")
    String email,

    @Schema(description = "年龄", minimum = "1", maximum = "150")
    Integer age
) {}

4. 独立编写 OpenAPI YAML（不依赖代码）

有时候想先设计 API，再写代码，可以直接写 yaml 文件，然后用 Swagger Editor 在线编辑。

官网编辑器：https://editor.swagger.io

基础模板（OpenAPI 3.0.3）：

openapi: 3.0.3
info:
  title: 用户服务API
  version: 1.0.0
  description: 用户管理相关接口
servers:
  - url: https://api.example.com/v1
    description: 生产环境
  - url: http://localhost:8080
    description: 本地开发
paths:
  /users/{id}:
    get:
      summary: 根据ID查询用户
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: integer
        username:
          type: string
        email:
          type: string
          format: email

5. 常用工具集合（2025）

工具	用途
https://editor.swagger.io	在线编辑、预览、生成代码
Swagger UI	美观文档页面
Redoc	另一款更漂亮的文档渲染工具
Stop swagger-codegen / openapi-generator	根据 yaml 生成多语言客户端/服务端代码
Postman → OpenAPI 导出	Postman 集合可直接导出 OpenAPI 文件

6. 快速上手 Demo 项目（强烈推荐直接克隆运行）

GitHub 最火的 springdoc 示例（持续更新）：
https://github.com/springdoc/springdoc-openapi-demos

总结学习路径

1. 先用 springdoc 在 Spring Boot 项目中跑通（10分钟）
2. 掌握常用注解
3. 学会用 https://editor.swagger.io 独立设计 API
4. 项目中统一配置分组、权限、版本、联系人等信息
5. 配合网关（Spring Cloud Gateway、Kong、Apifox Mock）使用

需要我给你一个完整的 Spring Boot 3 + springdoc + 登录鉴权 + 分组 + 多环境的完整项目模板吗？可以直接发你 zip 或 GitHub 仓库。