Swagger参数和复杂类型

Swagger 是一个用于设计、构建、记录和使用 RESTful Web 服务的框架

Swagger 参数

在 Swagger 中，参数分为以下几种类型：

1. Path 参数：在 URL 路径中的参数，如 /users/{userId}，其中 userId 是一个路径参数。
2. Query 参数：在 URL 查询字符串中的参数，如 /users?role=admin，其中 role 是一个查询参数。
3. Header 参数：在 HTTP 请求头中的参数，如 X-Api-Key: 123456，其中 X-Api-Key 是一个头参数。
4. Body 参数：在 HTTP 请求体中的参数，通常用于发送 JSON 或 XML 数据。
5. Form 参数：在 HTTP 请求表单中的参数，如 name=John&age=30。

在 Swagger 定义文件（YAML 或 JSON）中，你可以使用以下格式来描述参数：

parameters:
  - name: userId
    in: path
    description: 用户 ID
    required: true
    schema:
      type: integer
  - name: role
    in: query
    description: 用户角色
    schema:
      type: string

复杂类型

复杂类型是指包含多个属性的数据结构，如对象、数组等。在 Swagger 中，你可以使用 schema 关键字来定义复杂类型。

以下是一些常见的复杂类型示例：

对象

schema:
  type: object
  properties:
    name:
      type: string
    age:
      type: integer

数组

schema:
  type: array
  items:
    type: string

嵌套对象

schema:
  type: object
  properties:
    user:
      $ref: '#/components/schemas/User'

枚举

schema:
  type: string
  enum:
    - admin
    - user

在定义复杂类型时，你可以使用 $ref 关键字来引用其他预定义的类型，以实现更高级别的复用。

在 Swagger 定义文件中，你还可以使用 components 关键字来定义可重用的组件，如模式、响应和参数。例如：

components:
  schemas:
    User:
      type: object
      properties:
        name:
          type: string
        age:
          type: integer

通过这种方式，你可以更好地组织和管理 Swagger 文档，使其更具可读性和可维护性。