Swagger: Representing enum property in hash error

Question

I am currently working on a Swagger documentation for Ruby on Rails API. The API has lots of enumerators (enums) which are included in various models. The enums are stored as hashes and not arrays in the app/models/concerns directory so that they can be modified without issues later.

State Enum (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

However, when I try to represent this in a component schema in Swagger like this:

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

I get an error:

should not have additional properties

state1: 'State 1'

state2: 'State 2'

state3: 'State 3'

state4: 'State 4'

state5: 'State 5'

I want to represent the enums in hashes and not in arrays. Is there any workaround I can get to make this work?

Answer 1

I finally figured out a way to get it done. This solution applies to OpenAPI 3 – the latest version of the OpenAPI Specification as the point of answering this question.

Here's how I did it:

Solution 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

This was passing the entire hash into the response body of a request, and thus it was throwing errors

Solution 2:

Another way is to represent them as arrays, which was not my ideal solution, but it allowed Swagger to select only one item from the array to pass into the response body of a request. I would, however, take note that the enums are hashes and I will have to do a collection_select of hashes for the enums on my client-side.

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

Lastly, whichever solution you choose you can then reference them in other models like this:

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'

Here's a link to the Swagger Documentation: Dictionaries, HashMaps and Associative Arrays

That's all.

I hope this helps