Swagger Editor 无法使用枚举类型参数解析定义

Question

我使用 Swagger Editor 呈现 API 文档并生成 Python 客户端。

我已经为 one of public APIs 导入了 Swagger JSON 定义，该定义已由编辑器转换为 YAML。

但是，对于 enum 类型的参数，我收到以下错误：

Structural error at paths./aggregates/metadata.get.parameters.0.type
should be equal to one of the allowed values
allowedValues: string, number, boolean, integer, array
Jump to line 23

是 Swagger Editor 中的错误、我选择的定义中的错误还是某些版本不兼容？

这是 YAML 中的相关 Swagger 定义：

swagger: '2.0'
info:
  version: v1
  title: BDL API
  termsOfService: ''
basePath: /api/v1
paths:
  /aggregates/metadata:
    get:
      tags:
        - Aggregates
      summary: Metadane / Metadata
      operationId: AggregatesMetadataGet
      consumes: []
      produces:
        - application/json
        - application/xml
      parameters:
        - name: lang
          in: query
          description: ''
          required: false
          type: enum
          enum:
            - pl
            - en

Answer 1

将 type: enum 替换为 type: string。这是 API 定义中的语法错误，而不是 Swagger 编辑器问题。

该定义中的另一个问题是操作中的冗余 Accept 参数：

  /aggregates/metadata:
    get:
      ...
      produces:
        - application/json
        - application/xml
      parameters:
        - ...
        - name: Accept    # <-----
          in: header
          description: ...
          required: false
          type: string
          enum:
            - application/json
            - application/xml

Acceptheader由produces关键字控制，不需要定义为参数。这在技术上不是错误，但可能会导致工具出现问题。

Swagger Editor 无法使用枚举类型参数解析定义

Swagger Editor fails to parse definition with enum type parameters

swagger

swagger-2.0