跳到内容

描述请求体

请求体通常用于“创建”和“更新”操作（POST、PUT、PATCH）。例如，当使用 POST 或 PUT 创建资源时，请求体通常包含要创建的资源的表示形式。OpenAPI 3.0 提供了 requestBody 关键字来描述请求体。

与 OpenAPI 2.0 的差异

如果您之前使用过 OpenAPI 2.0，这里是对更改的总结，可帮助您开始使用 OpenAPI 3.0

  • body 和 form 参数已替换为 requestBody。
  • 现在，操作可以同时使用表单数据和其他媒体类型（如 JSON）。
  • consumes 数组已替换为 requestBody.content 映射，该映射将媒体类型映射到它们的模式。
  • 模式可以因媒体类型而异。
  • anyOf 和 oneOf 可用于指定备用模式。
  • 表单数据现在可以包含对象，并且您可以为对象和数组指定序列化策略。
  • GET、DELETE 和 HEAD 不再允许有请求体，因为根据 RFC 7231，它没有定义的语义。

requestBody、content 和媒体类型

与 OpenAPI 2.0 使用 body 和 formData 参数定义请求体不同，OpenAPI 3.0 使用 requestBody 关键字来区分有效负载与参数（如查询字符串）。requestBody 更加灵活，因为它允许您使用不同的媒体类型，如 JSON、XML、表单数据、纯文本等，并为不同的媒体类型使用不同的模式。requestBody 由 content 对象、一个可选的 Markdown 格式的 description 和一个可选的 required 标志（默认为 false）组成。content 列出操作使用的媒体类型（如 application/json）并为每种媒体类型指定 schema。默认情况下，请求体是可选的。要将请求体标记为必需，请使用 required: true。

1
paths:
2
  /pets:
3
    post:
4
      summary: Add a new pet
5


6
      requestBody:
7
        description: Optional description in *Markdown*
8
        required: true
9
        content:
10
          application/json:
11
            schema:
12
              $ref: "#/components/schemas/Pet"
13
          application/xml:
14
            schema:
15
              $ref: "#/components/schemas/Pet"
16
          application/x-www-form-urlencoded:
17
            schema:
18
              $ref: "#/components/schemas/PetForm"
19
          text/plain:
20
            schema:
21
              type: string
22


23
      responses:
24
        "201":
25
          description: Created

content 允许使用通配符媒体类型。例如，image/* 表示所有图像类型；*/* 表示所有类型，并且在功能上等同于 application/octet-stream。在解释规范时，特定媒体类型优先于通配符媒体类型，例如，image/png > image/* > */*。

1
paths:
2
  /avatar:
3
    put:
4
      summary: Upload an avatar
5
      requestBody:
6
        content:
7
          image/*: # Can be image/png, image/svg, image/gif, etc.
8
            schema:
9
              type: string
10
              format: binary

anyOf, oneOf

OpenAPI 3.0 支持 anyOf 和 oneOf，因此您可以为请求体指定备用模式

1
requestBody:
2
  description: A JSON object containing pet information
3
  content:
4
    application/json:
5
      schema:
6
        oneOf:
7
          - $ref: "#/components/schemas/Cat"
8
          - $ref: "#/components/schemas/Dog"
9
          - $ref: "#/components/schemas/Hamster"

文件上传

要了解如何描述文件上传，请参阅文件上传和多部分请求。

请求体示例

请求体可以有一个 example 或多个 examples。example 和 examples 是 requestBody.content.<media-type> 对象的属性。如果提供，这些示例将覆盖模式提供的示例。例如，如果请求和响应使用相同的模式，但您想拥有不同的示例，这将非常方便。example 允许一个内联示例

1
requestBody:
2
  content:
3
    application/json:
4
      schema:
5
        $ref: "#/components/schemas/Pet"
6
      example:
7
        name: Fluffy
8
        petType: dog

examples（复数）更加灵活——您可以有一个内联示例、一个 $ref 引用，或者指向包含有效负载示例的外部 URL。每个示例还可以具有可选的 summary 和 description，用于文档编制。

1
requestBody:
2
  content:
3
    application/json:
4
      schema:
5
        $ref: '#/components/schemas/Pet'
6
      examples:
7


8
        dog:  # <--- example name
9
          summary: An example of a dog
10
          value:
11
            # vv Actual payload goes here vv
12
            name: Fluffy
13
            petType: dog
14


15
        cat:  # <--- example name
16
          summary: An example of a cat
17
          externalValue: http://api.example.com/examples/cat.json   # cat.json contains {"name": "Tiger", "petType": "cat"}
18


19
        hamster:  # <--- example name
20
          $ref: '#/components/examples/hamster'
21


22
  components:
23
    examples:
24
      hamster:  # <--- example name
25
        summary: An example of a hamster
26
        value:
27
          # vv Actual payload goes here vv
28
          name: Ginger
29
          petType: hamster

有关更多信息，请参阅添加示例。

可重用的请求体

您可以将请求体定义放在全局 components.requestBodies 部分，并在其他地方 $ref 它们。如果多个操作具有相同的请求体，这将非常方便——这样您就可以轻松地重用相同的定义。

1
paths:
2
  /pets:
3
    post:
4
      summary: Add a new pet
5
      requestBody:
6
        $ref: '#/components/requestBodies/PetBody'
7


8
  /pets/{petId}
9
    put:
10
      summary: Update a pet
11
      parameters: [ ... ]
12
      requestBody:
13
        $ref: '#/components/requestBodies/PetBody'
14


15
components:
16
  requestBodies:
17
    PetBody:
18
      description: A JSON object containing pet information
19
      required: true
20
      content:
21
        application/json:
22
          schema:
23
            $ref: '#/components/schemas/Pet'

表单数据

术语“表单数据”用于媒体类型 application/x-www-form-urlencoded 和 multipart/form-data，它们通常用于提交 HTML 表单。

  • application/x-www-form-urlencoded 用于将简单的 ASCII 文本数据作为 key=value 对发送。有效负载格式类似于查询参数。
  • multipart/form-data 允许在单个消息中提交二进制数据以及多种媒体类型（例如，图像和 JSON）。每个表单字段在有效负载中都有自己的部分，其中包含内部 HTTP 标头。multipart 请求通常用于文件上传。

为了说明表单数据，请考虑一个 HTML POST 表单

1
<form action="http://example.com/survey" method="post">
2
  <input type="text" name="name" />
3
  <input type="number" name="fav_number" />
4
  <input type="submit" />
5
</form>

此表单将数据 POST 到表单的端点

1
POST /survey HTTP/1.1
2
Host: example.com
3
Content-Type: application/x-www-form-urlencoded
4
Content-Length: 28
5


6
name=Amy+Smith&fav_number=42

在 OpenAPI 3.0 中，表单数据使用 type: object 模式建模，其中对象属性表示表单字段

1
paths:
2
  /survey:
3
    post:
4
      requestBody:
5
        required: true
6
        content:
7
          application/x-www-form-urlencoded:
8
            schema:
9
              type: object
10
              properties:
11
                name: # <!--- form field name
12
                  type: string
13
                fav_number: # <!--- form field name
14
                  type: integer
15
              required:
16
                - name
17
                - email

表单字段可以包含原始值、数组和对象。默认情况下，数组序列化为 array_name=value1&array_name=value2，对象序列化为 prop1=value1&prop=value2，但是你可以使用 OpenAPI 3.0 规范中定义的其他序列化策略。序列化策略在 encoding 部分中指定，如下所示

1
requestBody:
2
  content:
3
    application/x-www-form-urlencoded:
4
      schema:
5
        type: object
6
        properties:
7
          color:
8
            type: array
9
            items:
10
              type: string
11
      encoding:
12
        color: # color=red,green,blue
13
          style: form
14
          explode: false

默认情况下，application/x-www-form-urlencoded 主体内的表单字段值中的保留字符 :/?#[]@!$&'()*+,;= 在发送时会被百分比编码。要允许这些字符按原样发送，请使用 allowReserved 关键字，如下所示

1
requestBody:
2
  content:
3
    application/x-www-form-urlencoded:
4
      schema:
5
        type: object
6
        properties:
7
          foo:
8
            type: string
9
          bar:
10
            type: string
11
          baz:
12
            type: string
13
      encoding:
14
        # Don't percent-encode reserved characters in the values of "bar" and "baz" fields
15
        bar:
16
          allowReserved: true
17
        baz:
18
          allowReserved: true

可以使用自由格式模式来建模任意的 key=value 对

1
requestBody:
2
  content:
3
    application/x-www-form-urlencoded:
4
      schema:
5
        type: object
6
        additionalProperties: true # this line is optional

表单数据中的复杂序列化

style 和 explode 关键字提供的序列化规则仅为原始数组和具有原始属性的对象定义了行为。对于更复杂的情况，例如表单数据中的嵌套数组或 JSON，你需要使用 contentType 关键字来指定用于编码复杂字段值的媒体类型。以Slack incoming webhooks为例。消息可以直接作为 JSON 发送，也可以将 JSON 数据发送到名为 payload 的表单字段中，如下所示（在应用 URL 编码之前）

1
payload={"text":"Swagger is awesome"}

这可以描述为

1
openapi: 3.0.0
2
info:
3
  version: 1.0.0
4
  title: Slack Incoming Webhook
5
externalDocs:
6
  url: https://api.slack.com/incoming-webhooks
7


8
servers:
9
  - url: https://hooks.slack.com
10


11
paths:
12
  /services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX:
13
    post:
14
      summary: Post a message to Slack
15
      requestBody:
16
        content:
17
          application/json:
18
            schema:
19
              $ref: "#/components/schemas/Message"
20


21
          application/x-www-form-urlencoded:
22
            schema:
23
              type: object
24
              properties:
25
                payload: # <--- form field that contains the JSON message
26
                  $ref: "#/components/schemas/Message"
27
            encoding:
28
              payload:
29
                contentType: application/json
30


31
      responses:
32
        "200":
33
          description: OK
34


35
components:
36
  schemas:
37
    Message:
38
      title: A Slack message
39
      type: object
40
      properties:
41
        text:
42
          type: string
43
          description: Message text
44
      required:
45
        - text

参考

请求体对象

媒体类型对象

没有找到你要找的内容？ 向社区提问
发现错误？ 请告知我们

Swagger 开源
Swagger
专业工具
资源