Techioz Blog

Swagger: ハッシュ エラーでの enum プロパティの表現

概要

私は現在、Ruby on Rails API の Swagger ドキュメントに取り組んでいます。 API には、さまざまなモデルに含まれる多数の列挙子 (enum) があります。列挙型は 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' }

エラーが発生します:

列挙型を配列ではなくハッシュで表現したいと考えています。これを機能させるための回避策はありますか?

解決策

ついにそれを実現する方法を見つけました。 このソリューションは、この質問に答える時点での OpenAPI 仕様の最新バージョンである OpenAPI 3 に適用されます。

私がやった方法は次のとおりです。

解決策 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

これはハッシュ全体をリクエストの応答本文に渡していたため、エラーがスローされていました

解決策 2:

もう 1 つの方法は、それらを配列として表すことです。これは私の理想的なソリューションではありませんでしたが、これにより、Swagger は配列から項目を 1 つだけ選択して、リクエストの応答本文に渡すことができました。ただし、列挙型はハッシュであるため、クライアント側で列挙型のハッシュの collection_select を実行する必要があることに注意してください。

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 ドキュメントへのリンクは次のとおりです: 辞書、ハッシュマップ、連想配列

それだけです。

これがお役に立てば幸いです