Trending: Microservices Architecture GuideMySQL Fundamentals for Backend DevelopersJava Backend Interview: The 15 Questions That Come UpRedis: Caching, Data Structures & PersistenceCache Patterns and Pitfalls

Swagger 文档实例

一份完整的用户 CRUD 规范：请求体、错误响应、枚举、示例、鉴权。

Intermediate
Key Points完整规范的标志是：每个 operation 都有 requestBody/responses，错误结构与成功结构都在 components 里，安全方案集中声明。

完整规范

YAML
openapi: 3.0.3
info:
  title: User API
  version: 1.0.0
servers:
  - url: https://api.example.com/v1
security:
  - bearerAuth: []
paths:
  /users:
    get:
      tags: [Users]
      summary: 用户列表
      parameters:
        - $ref: '#/components/parameters/Page'
        - $ref: '#/components/parameters/Size'
        - name: status
          in: query
          schema:
            $ref: '#/components/schemas/UserStatus'
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserPage'
    post:
      tags: [Users]
      summary: 创建用户
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserCreate'
      responses:
        '201':
          description: 已创建
          headers:
            Location:
              schema:
                type: string
              description: 新资源地址
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '422':
          $ref: '#/components/responses/ValidationFailed'
  /users/{id}:
    parameters:
      - $ref: '#/components/parameters/UserId'
    get:
      tags: [Users]
      summary: 查询单个用户
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      tags: [Users]
      summary: 删除用户
      responses:
        '204':
          description: 已删除
        '404':
          $ref: '#/components/responses/NotFound'

components

YAML
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
  parameters:
    Page:
      name: page
      in: query
      schema: { type: integer, minimum: 1, default: 1 }
    Size:
      name: size
      in: query
      schema: { type: integer, minimum: 1, maximum: 100, default: 20 }
    UserId:
      name: id
      in: path
      required: true
      schema: { type: integer, format: int64 }
  responses:
    NotFound:
      description: 资源不存在
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    ValidationFailed:
      description: 参数校验失败
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    UserStatus:
      type: string
      enum: [active, disabled]
    User:
      type: object
      required: [id, name, status]
      properties:
        id: { type: integer, format: int64 }
        name: { type: string, example: Alice }
        email: { type: string, format: email }
        status:
          $ref: '#/components/schemas/UserStatus'
        createdAt: { type: string, format: date-time }
    UserCreate:
      type: object
      required: [name, email]
      properties:
        name: { type: string, minLength: 1, maxLength: 64 }
        email: { type: string, format: email }
        age: { type: integer, minimum: 0, maximum: 150 }
    UserPage:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/User'
        total: { type: integer }
        page: { type: integer }
        size: { type: integer }
    Error:
      type: object
      required: [code, message]
      properties:
        code: { type: string, example: NOT_FOUND }
        message: { type: string }
        details:
          type: array
          items:
            type: object
            properties:
              field: { type: string }
              issue: { type: string }

几个容易漏的点

  • 路径级 parameters 写在 /{id} 下，所有方法共用
  • requestBody 是 3.0 的新概念，2.0 里是 parameters 里 in: body
  • 204 响应不要写 content，否则工具会生成空对象解析代码
  • security 可以在顶层声明，单个 operation 可覆盖为 security: []（公开）

Friends & Partners

新华字典在线查字汉语词典成语大全歇后语大全古诗词鉴赏网络热词专业术语大全