Swagger：Representing enum 属性 in hash error

Question

我目前正在 Rails API 上为 Ruby 编写 Swagger 文档。 API 有很多枚举器（枚举），它们包含在各种模型中。枚举存储为 hashes 而不是 arrays 在 app/models/concerns 目录中，以便以后可以毫无问题地修改它们。

状态枚举 (state.rb)

module State
  extend ActiveSupport::Concern
  included do
    enum state: { state1: 'State 1',
                  state2: 'State 2',
                  state3: 'State 3',
                  state4: 'State 4',
                  state5: 'State 5' }
  end
end

但是，当我尝试在 Swagger 的组件模式中表示时，如下所示：

components:
  schemas:
    State:
      type: object
      properties:
        enum: { state1: 'State 1',
                state2: 'State 2',
                state3: 'State 3',
                state4: 'State 4',
                state5: 'State 5' }

我收到一个错误：

should not have additional properties

state1: 'State 1'

state2: 'State 2'

state3: 'State 3'

state4: 'State 4'

state5: 'State 5'

我想在 hashes 中表示枚举，而不是在 arrays 中。有什么解决方法可以使这项工作正常进行吗？谢谢。

Answer 1

我终于想出了一个办法来完成它。此解决方案适用于 OpenAPI 3 – OpenAPI 规范的最新版本作为回答此问题的重点。

我是这样做的:

解决方案 1

components:
  schemas:
    State:
      type: object
      additionalProperties:
        type: string
      example:
        state1: State 1
        state2: State 2
        state3: State 3
        state4: State 4
        state5: State 5

这是将整个哈希传递到请求的响应正文中，因此它会抛出错误

方案二：

另一种方法是将它们表示为数组，这不是我理想的解决方案，但它允许 Swagger select 仅将数组中的一项传递到请求的响应主体中。但是，我会注意到枚举是散列，我将不得不为客户端的枚举执行 collection_select of hashes。

components:
  schemas:
    State:
      type: string
      description: List of States
      enum:
        - State 1
        - State 2
        - State 3
        - State 4
        - State 5

最后，无论您选择哪种解决方案，您都可以在其他模型中引用它们，如下所示：

components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: integer
          format: int64
        first_name:
          type: string
        last_name:
          type: string
        password:
          type: string
          format: password
        state:
          $ref: '#/components/schemas/State'

这是 Swagger 文档的 link：Dictionaries, HashMaps and Associative Arrays

就这些了。

希望对您有所帮助

Swagger：Representing enum 属性 in hash error

Swagger: Representing enum property in hash error

ruby

enums

ruby-on-rails

swagger

openapi