你就快到了,你只需要定义一个schema
的回应。这schema
定义与此状态代码关联的所有内容类型的响应结构。
例如,如果操作返回以下 JSON:
[
{
"petType": "dog",
"name": "Fluffy"
},
{
"petType": "cat",
"name": "Crookshanks"
}
]
以及这个 CSV:
petType,name
dog,Fluffy
cat,Crookshanks
你会使用:
# YAML
responses:
200:
description: OK
schema:
type: array
items:
type: object
properties:
petType:
type: string
name:
type: string
更多信息:描述回应 https://swagger.io/docs/specification/2-0/describing-responses/
在 OpenAPI 3.0 中,内容类型定义得到了改进,并且架构可能因内容类型而异:
openapi: 3.0.0
...
paths:
/some/endpoint:
get:
responses:
'200':
description: OK
content:
# JSON data is an object
application/json:
schema:
type: object
properties:
message:
type: string
# CSV data is a string of text
text/csv:
schema:
type: string
默认响应GET /some/endpoint
是一个 csv 文件,但如果format
查询参数的使用方式如下/some/endpoint?format=json
,响应将采用 json 格式。
目前无法将特定响应映射到特定操作参数,但 OpenAPI 规范存储库中有几个相关提案:
- 通过允许路径中的查询参数来适应旧版 API https://github.com/OAI/OpenAPI-Specification/issues/123
- 路径规范中的查询字符串 https://github.com/OAI/OpenAPI-Specification/issues/164
- 支持一个操作每条路径有多个规范 https://github.com/OAI/OpenAPI-Specification/issues/182
- 超载 https://github.com/OAI/OpenAPI-Specification/issues/298