消息体内容

上一页展示了如何定义 API 端点，但它没有解释如何通过 content 字段描述响应的内容。本页阐明了这个重要字段，它也可以用于描述查询，如参数页面所示。

`content` 字段

此字段可在响应对象和请求主体对象中找到。它是一个将标准 RFC6838 媒体类型与 OpenAPI 媒体类型对象配对的映射。

响应对象在 API 端点页面中进行了说明。
请求主体对象在操作的参数和有效负载页面中进行了说明。

这允许以不同格式返回内容（或接受内容），每个格式都有一个不同的结构，由媒体类型对象描述。通配符适用于媒体类型，更具体的媒体类型优先于通用媒体类型。

content:
  application/json:
    ...
  text/html:
    ...
  text/*:
    ...

媒体类型对象

媒体类型对象描述了内容的结构，并提供了用于文档和模拟目的的示例（示例在文档页面中处理）。

结构在 schema 字段中描述，该字段将在下面解释。

content:
  application/json:
    schema:
      ...

架构对象

架构对象定义了一种数据类型，它可以是基本类型（整数、字符串等）、数组或对象，具体取决于其 type 字段。

type 是一个字符串，其可能的值为：number、string、boolean、array 和 object。根据所选类型，可以使用许多其他字段来进一步指定数据格式。

例如，对于 string 类型，可以使用 minLength 和 maxLength 来限制字符串的长度。类似地，integer 类型接受 minimum 和 maximum 值。无论类型如何，如果数据选项的数量都限制在特定集合中，则可以使用 enum 数组指定它。所有这些属性都在架构对象规范中列出。

范围受限的整数示例

content:
  application/json:
    schema:
      type: integer
      minimum: 1
      maximum: 100

仅具有三个有效选项的字符串示例

content:
  application/json:
    schema:
      type: string
      enum:
      - Alice
      - Bob
      - Carl

数组类型应该有一个 items 字段，它本身也是一个架构对象，并定义数组中每个元素的类型。此外，可以使用 minItems 和 maxItems 来限制数组的大小。

content:
  application/json:
    schema:
      type: array
      minItems: 1
      maxItems: 10
      items:
        type: integer

最后，对象类型应该有一个 properties 字段，该字段列出对象的属性。此字段是一个将属性名称与架构对象配对的映射，该对象定义了它们的类型。这允许构建尽可能复杂的数据类型。

以下示例定义了一个具有两个字段的对象：一个 productName 字符串和一个 productPrice 数字

content:
  application/json:
    schema:
      type: object
      properties:
        productName:
          type: string
        productPrice:
          type: number

井字棋示例

到目前为止给出的井字棋示例 API 只有一个端点，只有一个未指定的响应。以下代码段添加了对该内容的描述

openapi: 3.1.0
info:
  title: Tic Tac Toe
  description: |
    This API allows writing down marks on a Tic Tac Toe board
    and requesting the state of the board or of individual squares.
  version: 1.0.0
paths:
  # Whole board operations
  /board:
    get:
      summary: Get the whole board
      description: Retrieves the current state of the board and the winner.
      responses:
        "200":
          description: "OK"
          content:
            application/json:
              schema:
                type: object
                properties:
                    winner:
                      type: string
                      enum: [".", "X", "O"]
                      description: |
                        Winner of the game. `.` means nobody has won yet.
                    board:
                      type: array
                      maxItems: 3
                      minItems: 3
                      items:
                          type: array
                          maxItems: 3
                          minItems: 3
                          items:
                            type: string
                            enum: [".", "X", "O"]
                            description: |
                              Possible values for a board square.
                              `.` means empty square.
  ...

响应包含一个以 JSON 格式的对象，它有两个字段

winner 是一个字符串，只有三个可能的值：.、X 和 O。
board 是一个 3 元素数组，其中每个项目都是另一个 3 元素数组，有效地构建了一个 3x3 方阵。矩阵中的每个元素都是一个字符串，只有三个可能的值：.、X 和 O。

我们描述的这部分开始变得太大太复杂。响应架构的详细信息占用大量空间，掩盖了请求/响应结构。深层嵌套也使架构更难在更大的对象中找到。重复使用描述页面解释了如何命名 OpenAPI 描述 (OAD) 的部分以便重复使用它们（例如，上面出现两次的三个选项的字符串）。

摘要

本页展示了如何描述响应或查询的正文内容。更准确地说

content 字段将媒体类型映射到媒体类型对象。
每个媒体类型对象都有一个 schema 字段，用于描述一个架构对象。
架构对象定义了一种数据 type，可以使用多个属性（如 minimum、maximum、items、properties 等）进行自定义。

下一页解释了如何定义端点接受的参数。

消息体内容

content 字段

媒体类型对象

架构对象

井字棋示例

摘要

`content` 字段