swagger和openAPI: 描述请求正文

作者: Arvin Chen 分类: Swagger 来源: Break易站(www.breakyizhan.com)

请求主体通常用于“创建”和“更新”操作(POST,PUT,PATCH)。例如,当使用POST或PUT创建资源时,请求主体通常包含要创建的资源的表示形式。

OpenAPI 3.0提供了requestBody描述请求体的关键字。

与OpenAPI 2.0的差异

如果您之前使用过OpenAPI 2.0,以下是可帮助您开始使用OpenAPI 3.0的更改摘要:

  • 正文和表单参数被替换为requestBody
  • 现在操作可以使用表单数据和其他媒体类型,例如JSON。
  • consumes阵列被替换为requestBody.content其中媒体类型映射到其模式图。
  • 模式可以因媒体类型而异。
  • anyOfoneOf可用于指定备用模式。
  • 表单数据现在可以包含对象,并且您可以指定对象和数组的序列化策略。
  • GET,DELETE和HEAD不再具有请求体,因为它没有按照RFC 7231定义的语义。

requestBody,内容和媒体类型

与使用OpenAPI 2.0 bodyformData参数定义请求主体不同,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/pngimage/**/*

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支持anyOfoneOf,因此您可以为请求主体指定备用模式:

      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或多个examplesexample并且examplesrequestBody.content.<media-type>对象的属性。如果提供,这些示例会覆盖架构提供的示例。例如,如果请求和响应使用相同的模式,但您希望具有不同的示例,则这很方便。

example 允许一个内联示例:

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

所述examples(多个)都更灵活-你可以有一个内联例如,$ref参考,或指向包含所述有效负载例如一个外部URL。每个示例还可以具有可选summarydescription用于文档目的。

      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-urlencodedmultipart/form-data,它们通常用于提交HTML表单。

  • application/x-www-form-urlencoded用于以key=value成对的方式发送简单的ASCII文本数据。有效载荷格式与查询参数类似。
  • 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

表单数据中的复杂序列化

由关键字styleexplode关键字提供的序列化规则只对具有原始属性的基元和对象的数组定义了行为。对于更复杂的sceharios,例如表单数据中的嵌套数组或JSON,您需要使用contentType关键字指定用于编码复杂字段值的媒体类型。

考虑Slack传入的webhooks的例子。消息可以直接作为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:
  - 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
  •   本文标题:swagger和openAPI: 描述请求正文 - Break易站
    转载请保留页面地址:https://www.breakyizhan.com/swagger/2956.html
      微信返利机器人
      免费:淘宝,京东,拼多多优惠券
      腾讯,爱奇艺,优酷的VIP视频免费解析,免费看
      即刻扫描二维码,添加微信机器人!

    发表笔记

    电子邮件地址不会被公开。 必填项已用*标注