描述請求主體

請求主體通常用於「建立」和「更新」操作（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 可用於指定替代結構描述。
表單資料現在可以包含物件，而且您可以指定物件和陣列的序列化策略。
根據 RFC 7231，GET、DELETE 和 HEAD 不再允許有請求主體，因為它們沒有定義的語意。

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 傳入 Webhook 為例。訊息可以直接以 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

參考

請求主體物件

媒體類型物件

找不到您要找的內容嗎？向社群提問
發現錯誤？請告訴我們