描述请求体

OAS 3 本指南适用于 OpenAPI 3.0。如果您使用 OpenAPI 2.0，请参阅我们的 OpenAPI 2.0 指南。

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

与 OpenAPI 2.0 的区别

如果您以前使用过 OpenAPI 2.0，以下是一些更改的摘要，以帮助您开始使用 OpenAPI 3.0

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

requestBody、内容和媒体类型

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

paths:
  /pets:
    post:
      summary: Add a new pet

      requestBody:
        description: Optional description in *Markdown*
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Pet'
          application/xml:
            schema:
              $ref: '#/components/schemas/Pet'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/PetForm'
          text/plain:
            schema:
              type: string

      responses:
        '201':
          description: Created

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

paths:
  /avatar:
    put:
      summary: Upload an avatar
      requestBody:
        content:
          image/*:    # Can be image/png, image/svg, image/gif, etc.
            schema:
              type: string
              format: binary

anyOf、oneOf

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

      requestBody:
        description: A JSON object containing pet information
        content:
          application/json:
            schema:
              oneOf:
                - $ref: '#/components/schemas/Cat'
                - $ref: '#/components/schemas/Dog'
                - $ref: '#/components/schemas/Hamster'

文件上传

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

请求体示例

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

      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Pet'
            example:
              name: Fluffy
              petType: dog

examples（复数）更加灵活 - 您可以在内联示例、$ref 引用中，或者指向包含有效负载示例的外部 URL。每个示例还可以为文档目的提供可选的 summary 和 description。

      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Pet'
            examples:

              dog:  # <--- example name
                summary: An example of a dog
                value:
                  # vv Actual payload goes here vv
                  name: Fluffy
                  petType: dog

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

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

components:
  examples:
    hamster:  # <--- example name
      summary: An example of a hamster
      value:
        # vv Actual payload goes here vv
        name: Ginger
        petType: hamster

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

可重用正文

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

paths:
  /pets:
    post:
      summary: Add a new pet
      requestBody:
        $ref: '#/components/requestBodies/PetBody'

  /pets/{petId}
    put:
      summary: Update a pet
      parameters: [ ... ]
      requestBody:
        $ref: '#/components/requestBodies/PetBody'

components:
  requestBodies:
    PetBody:
      description: A JSON object containing pet information
      required: true
      content:
        application/json:
          schema:
            $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 表单

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

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

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

name=Amy+Smith&fav_number=42

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

paths:
  /survey:
    post:
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                name:          # <!--- form field name
                  type: string
                fav_number:    # <!--- form field name
                  type: integer
              required:
                - name
                - email

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

      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                color:
                  type: array
                  items:
                    type: string
            encoding:
              color:            # color=red,green,blue
                style: form
                explode: false

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

      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                foo:
                  type: string
                bar:
                  type: string
                baz:
                  type: string
            encoding:
              # Don't percent-encode reserved characters in the values of "bar" and "baz" fields
              bar:
                allowReserved: true
              baz:
                allowReserved: true

可以使用自由格式架构对任意 key=value 对进行建模

      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              additionalProperties: true    # this line is optional

表单数据中的复杂序列化

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

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

这可以描述为

openapi: 3.0.0
info:
  version: 1.0.0
  title: Slack Incoming Webhook
externalDocs:
  url: https://api.slack.com/incoming-webhooks

servers:
  - url: https://hooks.slack.com

paths:
  /services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX:
    post:
      summary: Post a message to Slack
      requestBody:
        content:
        
          application/json:
            schema:
              $ref: '#/components/schemas/Message'

          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                payload:     # <--- form field that contains the JSON message
                  $ref: '#/components/schemas/Message'
            encoding:
              payload:
                contentType: application/json

      responses:
        '200':
          description: OK

components:
  schemas:
    Message:
      title: A Slack message
      type: object
      properties:
        text:
          type: string
          description: Message text
      required:
        - text

参考

RequestBody 对象

MediaType 对象

没有找到您要找的东西？咨询社区
发现错误？告诉我们