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

Question

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

Answer 1

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

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

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

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

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

Answer 2

按照@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