如何解决我可以分离出组合模式并在 OpenAPI 中引用它吗?
一些背景:我在使用 openapi-codegenerator 时遇到了一些问题,我得到了一条建议 was:
分离出组合模式并在OpenAPI中引用 将你的组合模式移动到一个组件中,并在响应中 $refing 它:
components:
ResponseOneOfSchema:
oneOf:
- $ref to IdentityProblemDetails
- $ref to LanguageUsageProblemDetails
然后在响应中,$ref 到 ResponseOneOfSchema。
我对这个最小的 valid 工作示例架构的实际问题是,这两个在 OpenAPI 3.0 中是否等效(根据 swagger-validator,两者似乎都有效)?
---
openapi: 3.0.0
info:
title: Dummy API
version: 0.1.0
description: |
Some description about the Dummy API here...
paths:
/pets:
patch:
requestBody:
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/Cat'
- $ref: '#/components/schemas/Dog'
responses:
'200':
description: Updated
components:
schemas:
Dog:
type: object
properties:
bark:
type: boolean
breed:
type: string
enum: [Dingo,Husky,Retriever,Shepherd]
Cat:
type: object
properties:
hunts:
type: boolean
age:
type: integer
和
---
openapi: 3.0.0
info:
title: Dummy API
version: 0.1.0
description: |
Some description about the Dummy API here...
paths:
/pets:
patch:
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/OneOfCatDogSchema'
responses:
'200':
description: Updated
components:
schemas:
OneOfCatDogSchema:
oneOf:
- $ref: '#/components/schemas/Cat'
- $ref: '#/components/schemas/Dog'
Dog:
type: object
properties:
bark:
type: boolean
breed:
type: string
enum: [Dingo,Shepherd]
Cat:
type: object
properties:
hunts:
type: boolean
age:
type: integer
如果它们确实是等价的,那么如果还有其他带有 oneOf
的属性怎么办(我应该用 allOf
将它们全部包裹起来吗)?
allOf:
- $ref: '#/components/schemas/composedSchemaForOneOf'
- type: object
喜欢
---
openapi: 3.0.0
info:
title: Dummy API
version: 0.1.0
description: |
Some description about the Dummy API here...
paths:
/pets:
patch:
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/AnimalSpec'
responses:
'200':
description: Updated
components:
schemas:
AnimalSpec:
type: object
description: The description of the config
properties:
display_name:
type: string
description: The name of the animal.
example:
config:
description: |
The description of the config
default: {kind: Cat}
example: {kind: Cat}
discriminator:
propertyName: kind
mapping:
Cat: '#/components/schemas/Cat'
Dog: '#/components/schemas/Dog'
oneOf:
- $ref: '#/components/schemas/Cat'
- $ref: '#/components/schemas/Dog'
Dog:
type: object
properties:
bark:
type: boolean
breed:
type: string
enum: [Dingo,Shepherd]
Cat:
type: object
properties:
hunts:
type: boolean
age:
type: integer
->
---
openapi: 3.0.0
info:
title: Dummy API
version: 0.1.0
description: |
Some description about the Dummy API here...
paths:
/pets:
patch:
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/AnimalSpec'
responses:
'200':
description: Updated
components:
schemas:
AnimalSpec:
type: object
description: The description of the config
properties:
display_name:
type: string
description: The name of the animal.
example:
config:
description: |
The description of the config
default: {kind: Cat}
example: {kind: Cat}
discriminator:
propertyName: kind
mapping:
Cat: '#/components/schemas/Cat'
Dog: '#/components/schemas/Dog'
$ref: '#/components/schemas/OneOfCatDogSchema'
OneOfCatDogSchema:
oneOf:
- $ref: '#/components/schemas/Cat'
- $ref: '#/components/schemas/Dog'
Dog:
type: object
properties:
bark:
type: boolean
breed:
type: string
enum: [Dingo,Shepherd]
Cat:
type: object
properties:
hunts:
type: boolean
age:
type: integer
我已确认我在此处发布的所有 4 个规范都是符合 swagger-parser 的有效规范。
版权声明:本文内容由互联网用户自发贡献,该文观点与技术仅代表作者本人。本站仅提供信息存储空间服务,不拥有所有权,不承担相关法律责任。如发现本站有涉嫌侵权/违法违规的内容, 请发送邮件至 dio@foxmail.com 举报,一经查实,本站将立刻删除。