在 Swagger 2.0 中定义多个模型的数组 [英] Define array of multiple models in Swagger 2.0
问题描述
这是我第一次接触 Swagger,所以请保持温和.
This is my first foray into Swagger so please be gentle.
我有以下定义:
definitions:
Payload:
type: object
properties:
indicators:
type: array
items:
$ref: '#/definitions/Indicator'
Indicator:
type: object
properties:
type:
type: string
computeOn:
type: array
items:
type: string
default:
- close
parameters:
type: object
BBANDS:
properties:
type:
type: string
default: BBANDS
computeOn:
type: array
items:
type: string
default:
- close
parameters:
type: object
properties:
timeperiod:
type: integer
format: int32
default: 5
nbdevup:
type: integer
format: int32
default: 2
nbdevdn:
type: integer
format: int32
default: 2
matype:
type: integer
format: int32
default: 0
DEMA:
properties:
type:
type: string
default: DEMA
computeOn:
type: array
items:
type: string
default:
- close
parameters:
type: object
properties:
timeperiod:
type: integer
format: int32
default: 5
所以 Payload
有一个名为 indicator
的属性,它是一个 Indicator
数组.BBANDS
和 DEMA
是 type Indicator
的模型(我知道这不会转换为 Swagger).我想要做的是定义一个实际模型数组及其默认值,在本例中为 BBANDS
和 DEMA
.像这样:
So Payload
has a property called indicator
which is an array of Indicator
s. The BBANDS
and DEMA
are models which are of type Indicator
(which I know doesn't translate to Swagger). What I'd like to do is define an array of the actual models with their defaults, in this case BBANDS
and DEMA
. Something like this:
definitions:
Payload:
type: object
properties:
indicators:
type: array
items:
- '#/definitions/BBANDS'
- '#/definitions/DEMA'
或
definitions:
Payload:
type: object
properties:
indicators:
type: array
items:
- $ref '#/definitions/BBANDS'
- $ref '#/definitions/DEMA'
当然这两者都不起作用.原因是虽然 Indicator
模型正确地描述了 indicator
,但不同的 indicator
可以有不同的参数集.
Neither of which work of course. The reason is while the Indicator
model describes an indicator
correctly, different indicator
s can have a different parameter set.
有没有办法从本质上定义多个模型的列表,或者将 BBANDS
和 DEMA
模型映射到 Indicator
中?
Is there a way to essentially define a list of several models or perhaps map the BBANDS
and DEMA
models into Indicator
?
推荐答案
Swagger/OpenAPI 2.0 不支持 items
的多种类型,但有几种方法可以描述您的需求.
Swagger/OpenAPI 2.0 does not support multiple types for items
, but there are a couple of ways to describe what you need.
只要有一个字段是模型之间通用的,可以用来区分它们,就可以使用模型继承:
As long as you have one field that is common between the models and can be used to distinguish between them, you can use model inheritance:
https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#schemaDiscriminatorhttps://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#composition-and-inheritance-polymorphism
在您的示例中,此属性是 type
(type="BBANDS"
或 type="DEMA"
).所以你可以:
In your example, this property is type
(type="BBANDS"
or type="DEMA"
). So you can:
- 使用
allOf
从Indicator
继承BBANDS
和DEMA
模型. - 将
discriminator: type
添加到Indicator
以指示type
属性将用于区分子模型. - 将
Payload
定义为Indicator
的数组.这样它实际上可以是一个BBANDS
数组或一个DEMA
数组.
- Inherit the
BBANDS
andDEMA
models fromIndicator
by usingallOf
. - Add
discriminator: type
toIndicator
to indicate that thetype
property will be used to distinguish between the sub-models. - Define
Payload
as an array ofIndicator
. This way it can actually be an array ofBBANDS
or an array ofDEMA
.
definitions:
Payload:
type: object
properties:
indicators:
type: array
items:
$ref: '#/definitions/Indicator'
Indicator:
type: object
properties:
type:
type: string
# Limit the possible values if needed
#enum:
# - BBANDS
# - DEMA
computeOn:
type: array
items:
type: string
default:
- close
# The "type" property will be used to distinguish between the sub-models.
# The value of the "type" property MUST be the schema name, that is, "BBANDS" or "DEMA".
# (Or in other words, the sub-model schema names must match possible values of "type".)
discriminator: type
required:
- type
BBANDS:
allOf:
- $ref: '#/definitions/Indicator'
- type: object
properties:
parameters:
type: object
properties:
timeperiod:
type: integer
format: int32
default: 5
nbdevup:
type: integer
format: int32
default: 2
nbdevdn:
type: integer
format: int32
default: 2
matype:
type: integer
format: int32
default: 0
DEMA:
allOf:
- $ref: '#/definitions/Indicator'
- type: object
properties:
parameters:
type: object
properties:
timeperiod:
type: integer
format: int32
default: 5
选项 2 - 单一模型
如果所有参数
都是整数,你可以有一个单一的模型Indicator
,其中parameters
定义为一个hashmap.但在这种情况下,您将无法为特定指标类型定义确切的参数
.
Option 2 - Single Model
If all parameters
are integer, you can have a single model Indicator
with parameters
defined as a hashmap. But in this case you lose the ability to define the exact parameters
for specific indicator types.
definitions:
Indicator:
type: object
properties:
type:
type: string
enum:
- BBANDS
- DEMA
computeOn:
type: array
items:
type: string
default:
- close
parameters:
type: object
properties:
# This is a common parameter in both BBANDS and DEMA
timeperiod:
type: integer
format: int32
default: 5
# This will match additional parameters "nbdevup", "nbdevdn", "matype" in BBANDS
additionalProperties:
type: integer
这篇关于在 Swagger 2.0 中定义多个模型的数组的文章就介绍到这了,希望我们推荐的答案对大家有所帮助,也希望大家多多支持IT屋!