我正在尝试为我的单端点 API 提供 Swagger/Open Api 文档。
我的单一端点看起来像
POST: http://localhost/api/v1/process http://localhost/api/v1/process
帖子正文决定逻辑路径和响应模式
Body1: {"jsonClass": "AnimalsRankedByLifeSpan"}
Response1: schema-1
Body2: {"jsonClass": "AnimalsInRegion", "region":"Africa", "type":"lions"}
Response2: schema-2
文档的期望:每个 jsonClass 都被列为 swagger(或任何其他)中的单独调用,我可以使用规范来获取所有受支持的 jsonClass。
看起来不像,swagger支持这种设计。如果是的话,请给我举一些例子。
是否有任何其他 Api 文档框架可以用来为支持的每种 jsonClass 提供请求-响应文档?
OpenAPI 2.0 和 3.0 无法在同一操作中将不同的请求模式映射到不同的响应模式。这是相应的功能请求:支持每个路径有多个规范的操作(例如每个路径有多个 POST 操作) https://github.com/OAI/OpenAPI-Specification/issues/182
目前,如果您使用 OpenAPI 3.0,则可以使用oneOf
为请求和响应定义多个可能的模式。但是,您无法定义它Body1
产生schema-1
响应和Body2
产生schema-2
回复。您只能在操作中口头记录这一点description
.
openapi: 3.0.0
...
paths:
/foo:
post:
requestBody:
required: true
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/Body1'
- $ref: '#/components/schemas/Body2'
responses:
'200':
description: OK
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/schema-1'
- $ref: '#/components/schemas/schema-2'
本文内容由网友自发贡献,版权归原作者所有,本站不承担相应法律责任。如您发现有涉嫌抄袭侵权的内容,请联系:hwhale#tublm.com(使用前将#替换为@)