操作的参数和有效负载

上一页 展示了如何描述操作的响应格式，即操作的输出数据。另一方面，本页展示了如何指定输入数据，即补充端点和操作以完整描述请求的额外信息。

OpenAPI 提供两种机制来指定输入数据，参数和请求正文（消息有效负载）。参数通常用于识别资源，而消息有效负载则提供该资源的内容。

带星号的边是数组。
路径项和操作对象在 API 端点 页面中进行了说明。
媒体类型和模式对象在 消息正文的内容 页面中进行了说明。

参数对象

路径项 和 操作 对象中的 parameters 字段是一个数组，包含 参数对象。当在路径项对象中提供时，参数由该路径上的所有操作共享（可以在操作对象级别覆盖单个参数，但不能删除它们）。

每个 参数对象 描述一个参数，具有以下必填字段

  • in (string): 参数的位置，如下所示。
  • name (string): 区分大小写。在每个位置必须唯一。

其他可选字段包括

  • description (string): 用于文档说明。例如，可能包含使用示例。
  • required (boolean): 该参数是否必须存在。默认值为 false。

参数的类型、格式及其序列化可以使用其他字段来指定，如下一节所示。

参数位置

参数可以位于不同的位置，由 in 字段指示。最常见的参数位置是

  • path: 参数是此操作的路由（及其 URL）的一部分。参数的名称必须以 模板表达式 形式出现在路径中，即由花括号 {} 括起来。

    例如，路径 /users/{id} 必须包含至少一个用以下方法描述的参数

    paths:
  /users/{id}:
    get:
      parameters:
      - name: id
        in: path
        required: true

    注意：使用路径参数时，required 字段必须存在，并且必须为 true。

  • query: 参数附加到操作 URL 的查询字符串部分。

    例如，URL /users?id=1234 可以使用以下方法解析

    paths:
  /users:
    get:
      parameters:
      - name: id
        in: query

  • header: 参数作为请求的一部分，在自定义 HTTP 标头中发送。标头名称不区分大小写。

参数类型

大多数情况下，参数的类型可以使用 schema 字段中的 模式对象 来指定。模式对象允许定义基本类型或复杂类型（如数组或对象），并对它们施加额外的限制。例如

parameters:
- name: id
  in: query
  schema:
    type: integer
    minimum: 1
    maximum: 100

消息正文的内容 页面更详细地描述了模式对象。

在更高级的场景中，可以使用 content 字段。它提供媒体类型到 媒体类型对象 的单项条目映射（更多详细信息可以在 消息正文的内容 页面中找到）。

注意：schema 或 content 中必须存在且只能存在一个。它们不能同时出现。

参数序列化控制

style 字段描述了参数的序列化方式，其效果取决于参数的类型。因此，生成的矩阵相当复杂，可以在 参数对象 规范页面中查阅。

以下表格举例说明了最常见的样式 simple、form、label 和 matrix

  • 基本类型：例如，名为 id 且值为 1234 的整数。

    style simple form label matrix
      1234 id=1234 .1234 ;id=1234

  • 数组类型：例如，名为 ids 且包含整数 1、2 和 3 的数组。

    可以使用 explode 字段将数组的每个元素分成一个单独的参数。

    style simple form label matrix
    使用 explode=false 1,2,3 ids=1,2,3 .1.2.3 ;ids=1,2,3
    使用 explode=true 1,2,3 ids=1&ids=2&ids=3 .1.2.3 ;ids=1;ids=2;ids=3

  • 对象类型：例如，名为 color 且包含值为 1、2 和 3 的整数字段 R、G 和 B 的对象。

    同样，可以使用 explode 将每个字段分成一个单独的参数。

    style simple form label matrix
    使用 explode=false R,1,G,2,B,3 color=R,1,G,2,B,3 .R.1.G.2.B.3 ;color=R,1,G,2,B,3
    使用 explode=true R=1,G=2,B=3 R=1&G=2&B=3 .R=1.G=2.B=3 ;R=1;G=2;B=3

有关更多序列化选项，请参见 参数对象 规范。

请求正文对象

更新数据库中的记录时，参数通常用于识别记录，而消息正文提供其新内容。

请求的消息正文通过 操作对象 中的 requestBody 字段来指定，该字段是一个 请求正文对象。

paths:
  /board:
    put:
      requestBody:
        ...

请求正文对象 中唯一必填字段是 content，它在 消息正文的内容 页面中进行了详细说明。

提醒一下，以下代码段描述了一个操作，该操作具有一个 JSON 请求正文，其中包含一个值为 1 到 100 之间的单个整数。

      requestBody:
        content:
          application/json:
            schema:
              type: integer
              minimum: 1
              maximum: 100

请求正文对象还具有一个 description 字符串和一个 required 布尔值，用于说明消息有效负载是否为必需的。

井字棋示例

井字棋示例 API 包含两个端点，一个没有参数或请求正文 (/board)，另一个同时包含两者 (/board/{row}/{column})。第二个端点的相关代码片段如下所示，阅读完本页后应该很容易理解。

paths:
  # Single square operations
  /board/{row}/{column}:
    parameters:
      - name: row
        in: path
        required: true
        schema:
          type: integer
          minimum: 1
          maximum: 3
      - name: column
        in: path
        required: true
        schema:
          type: integer
          minimum: 1
          maximum: 3
    get:
      summary: Get a single board square
      responses:
        ...
    put:
      summary: Set a single board square
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: string
              enum: [".", "X", "O"]
      responses:
        ...
  • 两个操作 (get 和 put) 具有相同的参数，因为它们是在路径项级别描述的。
  • 参数是两个整数，分别名为 row 和 column，它们位于操作的路径中。这与包含 {row} 和 {column} 的路径名称相匹配。
  • put 操作另外还需要提供一个请求正文，该正文必须是以下三个提供的字符串之一：.、X 和 O。

完整的 井字棋示例 API 并不完全像上面的代码段，因为它重用了描述的一部分来消除冗余。这种技术在 重用描述 页面中进行了说明。

总结

本页展示了

  • 如何指定操作可以提供的两种类型的输入数据：parameters 和 requestBody。
  • 参数可以位于不同的位置 (path、query、headers)，并且它们的内容 (schema) 和序列化 (style) 可以高度自定义。
  • 请求正文使用 content 字段来指定，就像指定响应一样。

下一页 解释了如何重用 OpenAPI 描述的部分来消除冗余，从而减小文件大小和维护成本。