Swagger 文档实例

以下是=一个完整的 Swagger 文档示例，是一个用户管理系统 API 的详细规范。

这个文档描述了一个用户管理系统的API，包含了用户的基本信息、认证服务、数据模型等。

该 API 遵循 RESTful 风格，使用 JSON 格式进行数据交换。

我们可以使用 Swagger Editor 在线测试你的文档，在线地址：https://editor.swagger.io/。只需将你的 YAML 或 JSON 复制粘贴到编辑器中，右侧面板将显示可视化的 API 文档。

实例

openapi: 3.0.0
info:
  title: 我的第一个API
  description: |
    这是一个简单的API示例文档，展示了用户管理系统的基本功能。
    包括用户的查询、创建、更新和删除操作。
  version: 1.0.0
  contact:
    name: API 支持团队
    email: support@example.com
    url: https://www.example.com/support
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html

servers:
  - url: https://api.example.com/v1
    description: 生产环境
  - url: https://staging-api.example.com/v1
    description: 预发布环境
  - url: https://dev-api.example.com/v1
    description: 开发环境

tags:
  - name: 用户
    description: 用户管理相关操作
  - name: 认证
    description: 认证相关操作

paths:
  /users:
    get:
      tags:
        - 用户
      summary: 获取所有用户列表
      description: 返回系统中的所有用户信息，支持分页和筛选
      operationId: getUsers
      parameters:
        - name: limit
          in: query
          description: 返回结果的最大数量
          required: false
          schema:
            type: integer
            format: int32
            minimum: 1
            maximum: 100
            default: 20
        - name: offset
          in: query
          description: 分页偏移量
          required: false
          schema:
            type: integer
            format: int32
            minimum: 0
            default: 0
        - name: status
          in: query
          description: 按用户状态筛选
          required: false
          schema:
            type: string
            enum: [active, inactive, banned]
      responses:
        '200':
          description: 成功获取用户列表
          content:
            application/json:
              schema:
                type: object
                properties:
                  total:
                    type: integer
                    description: 总用户数
                  users:
                    type: array
                    items:
                      $ref: '#/components/schemas/User'
              example:
                total: 2
                users:
                  - id: 1
                    username: "john_doe"
                    email: "john@example.com"
                    status: "active"
                    createdAt: "2023-05-01T12:00:00Z"
                  - id: 2
                    username: "jane_smith"
                    email: "jane@example.com"
                    status: "active"
                    createdAt: "2023-05-02T14:30:00Z"
        '400':
          description: 无效请求
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
      security:
        - bearerAuth: []
   
    post:
      tags:
        - 用户
      summary: 创建新用户
      description: 在系统中创建一个新用户
      operationId: createUser
      requestBody:
        description: 用户信息
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NewUser'
            example:
              username: "new_user"
              email: "new_user@example.com"
              password: "securePassword123"
      responses:
        '201':
          description: 用户创建成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
              example:
                id: 3
                username: "new_user"
                email: "new_user@example.com"
                status: "active"
                createdAt: "2023-05-10T09:15:00Z"
        '400':
          description: 无效请求
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                code: 400
                message: "邮箱格式不正确"
        '409':
          description: 资源冲突
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                code: 409
                message: "用户名已存在"
        '401':
          $ref: '#/components/responses/UnauthorizedError'
      security:
        - bearerAuth: []

  /users/{userId}:
    parameters:
      - name: userId
        in: path
        description: 用户ID
        required: true
        schema:
          type: integer
          format: int64
   
    get:
      tags:
        - 用户
      summary: 获取特定用户
      description: 根据ID获取特定用户的详细信息
      operationId: getUserById
      responses:
        '200':
          description: 成功获取用户信息
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserDetail'
              example:
                id: 1
                username: "john_doe"
                email: "john@example.com"
                firstName: "John"
                lastName: "Doe"
                phone: "+1234567890"
                status: "active"
                createdAt: "2023-05-01T12:00:00Z"
                lastLogin: "2023-05-10T08:30:00Z"
        '404':
          description: 用户不存在
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                code: 404
                message: "用户不存在"
        '401':
          $ref: '#/components/responses/UnauthorizedError'
      security:
        - bearerAuth: []
   
    put:
      tags:
        - 用户
      summary: 更新用户信息
      description: 更新特定用户的信息
      operationId: updateUser
      requestBody:
        description: 更新的用户信息
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateUser'
            example:
              firstName: "Jonathan"
              lastName: "Doe"
              phone: "+1987654321"
      responses:
        '200':
          description: 用户信息更新成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserDetail'
        '400':
          description: 无效请求
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: 用户不存在
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
      security:
        - bearerAuth: []
   
    delete:
      tags:
        - 用户
      summary: 删除用户
      description: 从系统中删除特定用户
      operationId: deleteUser
      responses:
        '204':
          description: 用户删除成功
        '404':
          description: 用户不存在
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
      security:
        - bearerAuth: []

  /auth/login:
    post:
      tags:
        - 认证
      summary: 用户登录
      description: 用户登录并获取访问令牌
      operationId: login
      requestBody:
        description: 登录凭证
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                username:
                  type: string
                  description: 用户名
                password:
                  type: string
                  format: password
                  description: 密码
              required:
                - username
                - password
            example:
              username: "john_doe"
              password: "password123"
      responses:
        '200':
          description: 登录成功
          content:
            application/json:
              schema:
                type: object
                properties:
                  accessToken:
                    type: string
                    description: JWT访问令牌
                  tokenType:
                    type: string
                    description: 令牌类型
                  expiresIn:
                    type: integer
                    description: 令牌过期时间（秒）
              example:
                accessToken: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
                tokenType: "Bearer"
                expiresIn: 3600
        '401':
          description: 登录失败
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                code: 401
                message: "用户名或密码错误"

  /auth/register:
    post:
      tags:
        - 认证
      summary: 用户注册
      description: 注册新用户并获取访问令牌
      operationId: register
      requestBody:
        description: 注册信息
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NewUser'
      responses:
        '201':
          description: 注册成功
          content:
            application/json:
              schema:
                type: object
                properties:
                  user:
                    $ref: '#/components/schemas/User'
                  accessToken:
                    type: string
                    description: JWT访问令牌
              example:
                user:
                  id: 3
                  username: "new_user"
                  email: "new_user@example.com"
                  status: "active"
                  createdAt: "2023-05-10T09:15:00Z"
                accessToken: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
        '400':
          description: 无效请求
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: 用户已存在
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: integer
          format: int64
          description: 用户唯一标识
        username:
          type: string
          description: 用户名
        email:
          type: string
          format: email
          description: 用户邮箱
        status:
          type: string
          enum: [active, inactive, banned]
          description: 用户状态
        createdAt:
          type: string
          format: date-time
          description: 创建时间
      required:
        - id
        - username
        - email
        - status
   
    UserDetail:
      allOf:
        - $ref: '#/components/schemas/User'
        - type: object
          properties:
            firstName:
              type: string
              description: 名字
            lastName:
              type: string
              description: 姓氏
            phone:
              type: string
              description: 电话号码
            lastLogin:
              type: string
              format: date-time
              description: 最后登录时间
   
    NewUser:
      type: object
      properties:
        username:
          type: string
          description: 用户名
          minLength: 3
          maxLength: 50
        email:
          type: string
          format: email
          description: 用户邮箱
        password:
          type: string
          format: password
          description: 用户密码
          minLength: 8
          maxLength: 100
        firstName:
          type: string
          description: 名字
        lastName:
          type: string
          description: 姓氏
        phone:
          type: string
          description: 电话号码
      required:
        - username
        - email
        - password
   
    UpdateUser:
      type: object
      properties:
        email:
          type: string
          format: email
          description: 用户邮箱
        firstName:
          type: string
          description: 名字
        lastName:
          type: string
          description: 姓氏
        phone:
          type: string
          description: 电话号码
        password:
          type: string
          format: password
          description: 新密码（如需更改）
          minLength: 8
          maxLength: 100
   
    Error:
      type: object
      properties:
        code:
          type: integer
          format: int32
          description: 错误代码
        message:
          type: string
          description: 错误消息
      required:
        - code
        - message

  responses:
    UnauthorizedError:
      description: 访问令牌丢失或无效
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            code: 401
            message: "未授权访问"

  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: 使用JWT Bearer Token进行身份验证

security:
  - bearerAuth: []

下面是文档的主要组成部分：

1. 基本信息部分

  • API标题和描述：用户管理系统的基本功能
  • 版本信息：1.0.0
  • 联系方式：API支持团队的联系信息
  • 许可证：Apache 2.0

2. 服务器配置

  • 生产环境
  • 预发布环境
  • 开发环境

3. API标签分类

  • 用户相关操作
  • 认证相关操作

4. 路径和操作

这个API包括以下端点：

用户管理

  • GET /users - 获取所有用户列表（支持分页和筛选）
  • POST /users - 创建新用户
  • GET /users/{userId} - 获取特定用户详情
  • PUT /users/{userId} - 更新用户信息
  • DELETE /users/{userId} - 删除用户

认证服务

  • POST /auth/login - 用户登录
  • POST /auth/register - 用户注册

5. 数据模型

  • User - 基本用户信息
  • UserDetail - 详细用户信息
  • NewUser - 创建用户的请求体
  • UpdateUser - 更新用户的请求体
  • Error - 错误响应

6. 安全定义

使用 JWT Bearer Token 进行 API 认证。

该文档遵循 OpenAPI 3.0.0 规范，包含了完整的请求参数、响应状态码、数据模型定义以及示例值。你可以将此 YAML 文档复制到 Swagger Editor 中查看可视化效果，或者集成到你的项目中。

这个文档可以作为你开发 RESTful API 的基础，随着项目发展可以进一步扩展和完善。