我有以下用于Swagger的YAML:
swagger: '2.0'
info:
...
host: adam.noncd.db.de
basePath: /api/v1.0
schemes:
- https
consumes:
- application/json
produces:
- application/json
paths:
/facilities:
get:
description: Access to the facilities known to the system
operationId: findFacilities
produces:
- application/json
parameters:
- name: type
in: query
description: type of the facility to filter by
default: ["ESCALATOR", "ELEVATOR"]
required: false
type: array
items:
enum: ["ESCALATOR", "ELEVATOR"]
collectionFormat: csv
uniqueItems: true
- name: state
in: query
description: the state of the facility to filter by
default: ["ACTIVE", "INACTIVE", "UNKNOWN"]
required: false
type: array
items:
enum: ["ACTIVE", "INACTIVE", "UNKNOWN"]
collectionFormat: csv
uniqueItems: true
responses:
'200':
description: facility data
schema:
type: array
items:
$ref: '#/definitions/facility'
'400':
description: The given filters contained invalid values.
'406':
description: The requested representation format is not available.
'500':
description: A processing error has occurred.
'503':
description: The service has been disabled temporarily.
'/facilities/{equipmentnumber}':
get:
description: Returns the facility identify by equipmentnumber
operationId: getFacilityByEquipmentNumber
produces:
- application/json
parameters:
- name: equipmentnumber
in: path
description: equipmentnumber of the facility to fetch
required: true
type: integer
format: int64
minimum: 1
responses:
'200':
description: Facility data
schema:
$ref: '#/definitions/facility'
'404':
description: The requested facility could not be found.
'406':
description: The requested representation format is not available.
'500':
description: A processing error has occurred.
'503':
description: The service has been disabled temporarily.
'/stations/{stationnumber}':
get:
description: Returns the railway station identified by stationnumber
operationId: findStationByStationNumber
produces:
- application/json
parameters:
- name: stationnumber
in: path
description: stationnumber of the station to fetch
required: true
type: integer
format: int64
minimum: 1
responses:
'200':
description: station data
schema:
$ref: '#/definitions/station'
'406':
description: Requested representation format is not available.
'500':
description: A processing error has occurred.
'503':
description: The service has been disabled temporarily.
definitions:
station:
type: object
required:
- stationnumber
- name
properties:
stationnumber:
type: integer
format: int64
description: "Identification number of the station"
name:
type: string
description: "Name of the station"
facilities:
type: array
items:
$ref: '#/definitions/facility'
facility:
type: object
required:
- equipmentnumber
- type
- state
- stationnumber
properties:
equipmentnumber:
type: integer
format: int64
'type':
type: string
enum: ["ESCALATOR", "ELEVATOR"]
'description':
type: string
description: Textual description of place
geocoordX:
type: number
format: double
description: geocoordinate component in DB REF format
geocoordY:
type: number
format: double
description: geocoordinate component in DB REF format
state:
type: string
enum: ["ACTIVE", "INACTIVE", "UNKNOWN"]
stationnumber:
type: integer
format: int64
当用Swagger Codegen生成Java客户端时,我收到以下警告:
[WARNING] no property from null, null, {ENUM=[ESCALATOR, ELEVATOR], TITLE=null, DESCRIPTION=null, DEFAULT=null, PATTERN=null, DESCRIMINATOR=null, MIN_ITEMS=null, MAX_ITEMS=null, MIN_PROPERTIES=null, MAX_PROPERTIES=null, MIN_LENGTH=null, MAX_LENGTH=null, MINIMUM=null, MAXIMUM=null, EXCLUSIVE_MINIMUM=null, EXCLUSIVE_MAXIMUM=null, UNIQUE_ITEMS=null, EXAMPLE=null, TYPE=null, FORMAT=null, READ_ONLY=null, VENDOR_EXTENSIONS={}}
[WARNING] no property from null, null, {ENUM=[ACTIVE, INACTIVE, UNKNOWN], TITLE=null, DESCRIPTION=null, DEFAULT=null, PATTERN=null, DESCRIMINATOR=null, MIN_ITEMS=null, MAX_ITEMS=null, MIN_PROPERTIES=null, MAX_PROPERTIES=null, MIN_LENGTH=null, MAX_LENGTH=null, MINIMUM=null, MAXIMUM=null, EXCLUSIVE_MINIMUM=null, EXCLUSIVE_MAXIMUM=null, UNIQUE_ITEMS=null, EXAMPLE=null, TYPE=null, FORMAT=null, READ_ONLY=null, VENDOR_EXTENSIONS={}}
...
[WARNING] warning! No inner type supplied for array parameter "type", using String
[WARNING] warning! No inner type supplied for array parameter "state", using String
正如您所看到的,Swagger为type
和state
使用字符串。在生成的API中,我得到了以下方法签名:
public List<Facility> findFacilities (List<String> type, List<String> state)
throws ApiException;
所以Swagger使用字符串而不是生成的枚举Facility.TypeEnum
和Facility.StateEnum
。显然,这与警告有关。因此,如果我设法"为数组参数提供内部类型",我想我也会在签名中获得枚举。但是我在YAML中找不到配置它。
如何修复我的YAML定义,使Swagger使用枚举而不是字符串
如何为数组参数提供内部类型
您需要提供有效的JSON模式来定义数组的内部类型。例如:
yaml
items:
enum: ["ACTIVE", "INACTIVE", "UNKNOWN"]
dosnot指定内部值的类型,只指定允许的值。正确的定义是:
items:
type: string
enum: ['ACTIVE', 'INACTIVE', 'UNKNOWN']
虽然这看起来是重复的(也就是说,可以从枚举中允许值的类型假设它是string
),但JSON模式希望您明确该类型。
按照@fehguy的建议添加type
属性将修复代码生成期间的警告,但生成的Java代码仍将使用List<String>
作为状态/类型参数。这是因为您指定为参数列表的内联枚举不会生成,它需要在definitions
部分中定义。
请注意,即使为内联参数规范生成了枚举代码,它也不会是您想要的枚举。您在swagger中内联指定的每个枚举都将获得自己独立的Java枚举实现,即使它们具有相同的值。因此,例如state
参数枚举类型将与facility
对象中定义的state
枚举类型没有连接。
解决方案是在definitions
部分中单独定义枚举,然后用$ref
引用这些定义,而不是使用内联定义。
注意:当前swagger codegen版本(2.1.4)中存在一个错误/缺少功能-Java枚举不是根据swagger枚举规范生成的。你需要从最新的github分支构建swagger codegen,让它现在就开始工作。
以下是使用显式枚举规范(states_enum
和types_enum
)和$ref
的修改的规范
swagger: '2.0'
info: foo
host: adam.noncd.db.de
basePath: /api/v1.0
schemes:
- https
consumes:
- application/json
produces:
- application/json
paths:
/facilities:
get:
description: Access to the facilities known to the system
operationId: findFacilities
produces:
- application/json
parameters:
- name: type
in: query
description: type of the facility to filter by
default: ["ESCALATOR", "ELEVATOR"]
required: false
type: array
items:
$ref: "#/definitions/types_enum"
collectionFormat: csv
uniqueItems: true
- name: state
in: query
description: the state of the facility to filter by
default: ["ACTIVE", "INACTIVE", "UNKNOWN"]
required: false
type: array
items:
$ref: "#/definitions/states_enum"
collectionFormat: csv
uniqueItems: true
responses:
'200':
description: facility data
schema:
type: array
items:
$ref: '#/definitions/facility'
'400':
description: The given filters contained invalid values.
'406':
description: The requested representation format is not available.
'500':
description: A processing error has occurred.
'503':
description: The service has been disabled temporarily.
'/facilities/{equipmentnumber}':
get:
description: Returns the facility identify by equipmentnumber
operationId: getFacilityByEquipmentNumber
produces:
- application/json
parameters:
- name: equipmentnumber
in: path
description: equipmentnumber of the facility to fetch
required: true
type: integer
format: int64
minimum: 1
responses:
'200':
description: Facility data
schema:
$ref: '#/definitions/facility'
'404':
description: The requested facility could not be found.
'406':
description: The requested representation format is not available.
'500':
description: A processing error has occurred.
'503':
description: The service has been disabled temporarily.
'/stations/{stationnumber}':
get:
description: Returns the railway station identified by stationnumber
operationId: findStationByStationNumber
produces:
- application/json
parameters:
- name: stationnumber
in: path
description: stationnumber of the station to fetch
required: true
type: integer
format: int64
minimum: 1
responses:
'200':
description: station data
schema:
$ref: '#/definitions/station'
'406':
description: Requested representation format is not available.
'500':
description: A processing error has occurred.
'503':
description: The service has been disabled temporarily.
definitions:
states_enum:
type: string
enum: ["ACTIVE", "INACTIVE", "UNKNOWN"]
types_enum:
type: string
enum: ["ESCALATOR", "ELEVATOR"]
station:
type: object
required:
- stationnumber
- name
properties:
stationnumber:
type: integer
format: int64
description: "Identification number of the station"
name:
type: string
description: "Name of the station"
facilities:
type: array
items:
$ref: '#/definitions/facility'
facility:
type: object
required:
- equipmentnumber
- type
- state
- stationnumber
properties:
equipmentnumber:
type: integer
format: int64
'type':
$ref: "#/definitions/types_enum"
'description':
type: string
description: Textual description of place
geocoordX:
type: number
format: double
description: geocoordinate component in DB REF format
geocoordY:
type: number
format: double
description: geocoordinate component in DB REF format
state:
$ref: "#/definitions/states_enum"
stationnumber:
type: integer
format: int64