如何在Swagger中为数组参数提供内部类型？

Question

我有以下YAML for Swagger：

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使用枚举而不是字符串？
如何为数组参数提供内部类型？

Answer 1

您需要提供有效的JSON模式来定义数组的内部类型。 例如：

yaml items: enum: ["ACTIVE", "INACTIVE", "UNKNOWN"]

dos 不指定内部值的类型，只是允许的值。 正确的定义是：

items:
  type: string
  enum: ['ACTIVE', 'INACTIVE', 'UNKNOWN']

虽然这似乎是重复的（意思是，可以从枚举中的允许值的类型假设它是一个string ），JSON模式希望您明确该类型。

Answer 2

按照@fehguy的建议添加type属性将修复代码生成期间的警告，但生成的Java代码仍将使用List<String>作为状态/类型参数。 这是因为您不会生成您指定为参数列表的内联枚举，需要在definitions部分中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