[英]How to document multiple content types in successful GET response in swagger
假设我们有一个示例 json swagger 规范:
{
"swagger": "2.0",
"info": {
"version": "1.0.0",
"title": "Some API"
},
"basePath": "/api/v1",
"consumes": [
"application/json"
],
"produces": [
"application/json",
"text/csv"
],
"paths": {
"/some/endpoint": {
"get": {
"parameters": [
{
"in": "body",
"name": "body",
"required": false,
"schema": {
"$ref": "#/definitions/BodyParamsDefinition"
}
}
],
"responses": {
"200": { ?? } ...
可以生成两种内容类型:
GET /some/endpoint
默认响应是一个 csv 文件,但如果像这样使用format
查询参数/some/endpoint?format=json
,则响应将采用 json 格式。
我很难找到如何以正确的响应完成我的规范。 当我使用这种方法时: https://swagger.io/docs/specification/describing-responses/我得到一个验证错误: ...get.responses['200'] should NOT have additional properties
您就快完成了,您只需要为响应定义一个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
更多信息:描述响应
在 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 规范存储库中有几个相关的建议:
声明:本站的技术帖子网页,遵循CC BY-SA 4.0协议,如果您需要转载,请注明本站网址或者原文地址。任何问题请咨询:yoyou2525@163.com.