Swagger：OpenAPI 规范的交互式文档

FreeGuideOnline 最新 2026-07-01

yaml openapi: 3.0.3 # 规范版本 info: # API 元信息 title: 用户管理API version: "1.0.0" servers: # 服务器地址

url: https://api.example.com/v1 paths: # 接口路径定义（核心） /users: get:
... 操作细节

components: # 可复用组件 schemas: responses: securitySchemes: security: # 全局安全设置


### 核心模块解读

#### info（必填）：描述你的 API

```yaml
info:
  title: 宠物商店API
  version: "1.0.0"
  description: 一个管理宠物的在线商店
  contact:
    email: support@petstore.com
  license:
    name: MIT

servers：指定 API 基础 URL

支持多环境切换，例如：

servers:
  - url: https://api.petstore.com/v1
    description: 正式环境
  - url: https://staging.petstore.com/v1
    description: 测试环境

paths：定义所有接口

每个路径可以包含一个或多个 HTTP 方法操作。下方是一个完整的 GET /users 示例：

paths:
  /users:
    get:
      summary: 获取用户列表
      description: 返回分页后的用户数据
      parameters:
        - name: page
          in: query
          description: 页码
          required: false
          schema:
            type: integer
            default: 1
      responses:
        '200':
          description: 成功响应
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserList'

components：定义可复用组件

避免重复定义，提高可维护性。常用组件包括 schemas（数据模型）、responses、parameters、securitySchemes 等。

components:
  schemas:
    User:
      type: object
      required:
        - id
        - name
      properties:
        id:
          type: integer
          format: int64
        name:
          type: string
          example: Alice
        email:
          type: string
          format: email
    UserList:
      type: array
      items:
        $ref: '#/components/schemas/User'

数据模型定义详解

OpenAPI 支持丰富的类型和验证规则：

类型	示例用法
string	`type: string`, `format: date-time`
number	`type: number`, `format: float`
integer	`type: integer`, `minimum: 1`
boolean	`type: boolean`
object	`type: object`, 包含 `properties`
array	`type: array`, `items: {...}`
enum	`type: string`, `enum: [A, B, C]`

结合 required、example、description 可以让模型描述精确且友好。

动手编写你的第一份 OpenAPI 文件

使用 Swagger Editor 在线编辑

打开 Swagger Editor。
左侧面板粘贴或编写 OpenAPI 内容，右侧实时预览 Swagger UI 效果。
编辑器提供语法提示和错误检测，非常适合入门。

下面是一份完整的最小化 OpenAPI 3.0 文档，你可以直接复制到 Editor 中体验：

openapi: 3.0.3
info:
  title: 图书管理 API
  version: "1.0.0"
servers:
  - url: http://localhost:8080/v1
paths:
  /books:
    get:
      summary: 获取全部图书
      responses:
        '200':
          description: 图书列表
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Book'
  /books/{bookId}:
    get:
      summary: 根据 ID 获取图书
      parameters:
        - name: bookId
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: 单本图书
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Book'
        '404':
          description: 未找到
components:
  schemas:
    Book:
      type: object
      properties:
        id:
          type: integer
        title:
          type: string
        author:
          type: string
        price:
          type: number
          format: float
      required:
        - id
        - title

理解结构后，增量添加细节

添加请求体：使用 requestBody 字段，支持多种媒体类型。
添加认证：定义 securitySchemes 并应用到具体操作。
添加标签：使用 tags 对接口分组，提升文档可读性。

安装与使用 Swagger UI

当你有了 OpenAPI 描述文件，就可以将其部署为交互式文档。

通过 Docker 运行 Swagger UI

docker run -p 8080:8080 -e SWAGGER_JSON=/openapi.yaml -v $(pwd)/openapi.yaml:/openapi.yaml swaggerapi/swagger-ui

然后访问 http://localhost:8080 即可看到文档，并能够向你的 API 发送请求。

在项目中集成 Swagger UI

很多服务端框架提供直接生成 OpenAPI 文件并集成 UI 的中间件，例如：

Spring Boot (Java)：结合 springdoc-openapi 依赖，自动扫描控制器生成文档。
Express (Node.js)：使用 swagger-jsdoc 和 swagger-ui-express 包。
FastAPI (Python)：内置 OpenAPI 生成，只需访问 /docs 即可看到 Swagger UI。

这种方式可以保证文档与代码实时同步，是最佳实践。

进阶技巧与最佳实践

使用 $ref 避免重复

当多个接口返回相同的错误结构时，可以定义全局 responses：

components:
  responses:
    NotFound:
      description: 资源未找到
      content:
        application/json:
          schema:
            type: object
            properties:
              code: { type: integer }
              message: { type: string }

然后在操作中引用：

responses:
  '404':
    $ref: '#/components/responses/NotFound'

为参数添加详细约束

让文档自动完成参数校验说明：

parameters:
  - name: age
    in: query
    schema:
      type: integer
      minimum: 0
      maximum: 120
    description: 用户年龄，应在 0-120 之间

善用 tags 和 operationId

tags 让 Swagger UI 中的接口分组清晰。
operationId 是每个操作唯一的标识，许多代码生成工具依赖它。

配合 Swagger Codegen 提升效率

安装 Swagger Codegen CLI，通过一行命令生成服务端存根：

swagger-codegen generate -i openapi.yaml -l spring -o /tmp/server

... 操作细节