媒体类型
媒体类型是请求或响应正文数据的格式。Web 服务操作可以接受和返回不同格式的数据,最常见的格式是 JSON、XML 和图像。您在请求和响应定义中指定媒体类型。以下是一个响应定义的示例
1paths:2 /employees:3 get:4 summary: Returns a list of employees.5 responses:6 "200": # Response7 description: OK8 content: # Response body9 application/json: # Media type10 schema: # Must-have11 type: object # Data type12 properties:13 id:14 type: integer15 name:16 type: string17 fullTime:18 type: boolean19 example: # Sample data20 id: 121 name: Jessica Right22 fullTime: true
在 responses
下,我们有各个响应的定义。如您所见,每个响应都由其代码定义(在我们的示例中为 '200'
)。代码下的关键字 content
对应于响应正文。一个或多个媒体类型作为此 content
关键字的子关键字。每个媒体类型都包含一个 schema
,用于定义消息正文的数据类型,以及可选的一个或多个示例。有关定义正文数据的更多信息,请参阅定义请求正文和定义响应。
媒体类型名称
content
字段下列出的媒体类型应符合 RFC 6838。例如,您可以使用标准类型或供应商特定类型(由 .vnd
指示)–
1application/json2application/xml3application/x-www-form-urlencoded4multipart/form-data5text/plain; charset=utf-86text/html7application/pdf8image/png
1application/vnd.mycompany.myapp.v2+json2application/vnd.ms-excel3application/vnd.openstreetmap.data+xml4application/vnd.github-issue.text+json5application/vnd.github.v3.diff6image/vnd.djvu
多种媒体类型
您可能需要指定多种媒体类型
1paths:2 /employees:3 get:4 summary: Returns a list of employees.5 responses:6 "200": # Response7 description: OK8 content: # Response body9 application/json: # One of media types10 schema:11 type: object12 properties:13 id:14 type: integer15 name:16 type: string17 fullTime:18 type: boolean19 application/xml: # Another media types20 schema:21 type: object22 properties:23 id:24 type: integer25 name:26 type: string27 fullTime:28 type: boolean
要为多种媒体类型使用相同的数据格式,请在规范的 components
部分中定义一个自定义对象,然后在每个媒体类型中引用此对象
1paths:2 /employees:3 get:4 responses:5 "200": # Response6 description: OK7 content: # Response body8 application/json: # Media type9 schema:10 $ref: "#/components/schemas/Employee" # Reference to object definition11 application/xml: # Media type12 schema:13 $ref: "#/components/schemas/Employee" # Reference to object definition14components:15 schemas:16 Employee: # Object definition17 type: object18 properties:19 id:20 type: integer21 name:22 type: string23 fullTime:24 type: boolean
要为多种媒体类型定义相同的格式,您还可以使用占位符,例如 */*
、application/*
、image/*
或其他
1paths:2 /info/logo:3 get:4 responses:5 "200": # Response6 description: OK7 content: # Response body8 image/*: # Media type9 schema:10 type: string11 format: binary
您用作媒体类型的值 - 在我们的示例中为 image/*
- 与您在 HTTP 请求和响应的 Accept
或 Content-Type
标头中看到的内容非常相似。不要混淆 Accept
或 Content-Type
标头的占位符和实际值。例如,响应正文的 image/*
占位符表示服务器将对所有与该占位符匹配的响应使用相同的数据结构。这并不意味着字符串 *image/* 将在 Content-Type
标头中指定。Content-Type
标头很可能具有 *image/png*、*image/jpeg* 或其他一些类似的值。
_没有找到您要找的内容?向社区提问 发现错误?告诉我们_OAS 3 本页是关于 OpenAPI 3.0 的。如果您使用 OpenAPI 2.0,请参阅OpenAPI 2.0 指南。
媒体类型
媒体类型是请求或响应正文数据的格式。Web 服务操作可以接受和返回不同格式的数据,最常见的格式是 JSON、XML 和图像。您在请求和响应定义中指定媒体类型。以下是一个响应定义的示例
1paths:2 /employees:3 get:4 summary: Returns a list of employees.5 responses:6 "200": # Response7 description: OK8 content: # Response body9 application/json: # Media type10 schema: # Must-have11 type: object # Data type12 properties:13 id:14 type: integer15 name:16 type: string17 fullTime:18 type: boolean19 example: # Sample data20 id: 121 name: Jessica Right22 fullTime: true
在 responses
下,我们有各个响应的定义。如您所见,每个响应都由其代码定义(在我们的示例中为 '200'
)。代码下的关键字 content
对应于响应正文。一个或多个媒体类型作为此 content
关键字的子关键字。每个媒体类型都包含一个 schema
,用于定义消息正文的数据类型,以及可选的一个或多个示例。有关定义正文数据的更多信息,请参阅定义请求正文和定义响应。
媒体类型名称
content
字段下列出的媒体类型应符合 RFC 6838。例如,您可以使用标准类型或供应商特定类型(由 .vnd
指示)–
1application/json2application/xml3application/x-www-form-urlencoded4multipart/form-data5text/plain; charset=utf-86text/html7application/pdf8image/png
1application/vnd.mycompany.myapp.v2+json2application/vnd.ms-excel3application/vnd.openstreetmap.data+xml4application/vnd.github-issue.text+json5application/vnd.github.v3.diff6image/vnd.djvu
多种媒体类型
您可能需要指定多种媒体类型
1paths:2 /employees:3 get:4 summary: Returns a list of employees.5 responses:6 "200": # Response7 description: OK8 content: # Response body9 application/json: # One of media types10 schema:11 type: object12 properties:13 id:14 type: integer15 name:16 type: string17 fullTime:18 type: boolean19 application/xml: # Another media types20 schema:21 type: object22 properties:23 id:24 type: integer25 name:26 type: string27 fullTime:28 type: boolean
要为多种媒体类型使用相同的数据格式,请在规范的 components
部分中定义一个自定义对象,然后在每个媒体类型中引用此对象
1paths:2 /employees:3 get:4 responses:5 "200": # Response6 description: OK7 content: # Response body8 application/json: # Media type9 schema:10 $ref: "#/components/schemas/Employee" # Reference to object definition11 application/xml: # Media type12 schema:13 $ref: "#/components/schemas/Employee" # Reference to object definition14components:15 schemas:16 Employee: # Object definition17 type: object18 properties:19 id:20 type: integer21 name:22 type: string23 fullTime:24 type: boolean
要为多种媒体类型定义相同的格式,您还可以使用占位符,例如 */*
、application/*
、image/*
或其他
1paths:2 /info/logo:3 get:4 responses:5 "200": # Response6 description: OK7 content: # Response body8 image/*: # Media type9 schema:10 type: string11 format: binary
您用作媒体类型的值 - 在我们的示例中为 image/*
- 与您在 HTTP 请求和响应的 Accept
或 Content-Type
标头中看到的内容非常相似。不要混淆 Accept
或 Content-Type
标头的占位符和实际值。例如,响应正文的 image/*
占位符表示服务器将对所有与该占位符匹配的响应使用相同的数据结构。这并不意味着字符串 *image/* 将在 Content-Type
标头中指定。Content-Type
标头很可能具有 *image/png*、*image/jpeg* 或其他一些类似的值。