OAS 2 此页面适用于 OpenAPI 规范版本 2（以前称为 Swagger）。要了解最新版本，请访问 OpenAPI 3 页面.

描述请求主体

POST、PUT 和 PATCH 请求可以包含请求主体（有效负载），例如 JSON 或 XML 数据。在 Swagger 术语中，请求主体称为 **主体参数**。虽然操作可能具有其他参数（路径、查询、标题），但只能有一个主体参数。

**注意：** 使用 表单参数 来描述 application/x-www-form-urlencoded 和 multipart/form-data 请求的有效负载，而不是主体参数。

主体参数在操作的参数部分定义，包括以下内容

• in: body
• schema 描述主体数据类型和结构。数据类型通常是对象，但也可以是基本类型（例如字符串或数字）或数组。
• 可选 description。
• 有效负载名称。它是必需的，但被忽略（它仅用于文档目的）。

对象有效负载（JSON 等）

许多 API 将数据传输为对象，例如 JSON。schema 用于对象的应指定 type: object 和该对象的属性。例如，POST /users 操作，其 JSON 主体如下

{
  "userName":  "Trillian",
  "firstName": "Tricia",
  "lastName":  "McMillan"
}

可以描述为

paths:
  /users:
    post:
      summary: Creates a new user.
      consumes:
        - application/json
      parameters:
        - in: body
          name: user
          description: The user to create.
          schema:
            type: object
            required:
              - userName
            properties:
              userName:
                type: string
              firstName:
                type: string
              lastName:
                type: string
      responses:
        201:
          description: Created

**注意：** 主体参数的名称被忽略。它仅用于文档目的。为了更模块化的样式，您可以将模式定义移动到全局 definitions 部分，并使用 $ref 来引用它们

paths:
  /users:
    post:
      summary: Creates a new user.
      consumes:
        - application/json
      parameters:
        - in: body
          name: user
          description: The user to create.
          schema:
            $ref: '#/definitions/User'     # <----------
      responses:
        200:
          description: OK
definitions:
  User:           # <----------
    type: object
    required:
      - userName
    properties:
      userName:
        type: string
      firstName:
        type: string
      lastName:
        type: string

基本类型主体

只想 POST/PUT 一个值？没问题，您可以将主体模式类型定义为基本类型，例如字符串或数字。原始请求

POST /status HTTP/1.1
Host: api.example.com
Content-Type: text/plain
Content-Length: 42

Time is an illusion. Lunchtime doubly so.

Swagger 定义

paths:
  /status:
    post:
      summary: Updates the status message.
      consumes:
        - text/plain      # <----------
      parameters:
        - in: body
          name: status
          required: true
          schema:
            type: string  # <----------
      responses:
        200:
          description: Success!

没有找到您要找的内容？ 询问社区
发现错误？ 告诉我们