CODEWITHSUNDEEP
swaggerswagger-uiswagger-2.0openapi
eloleon
eloleon

Reputation: 1254

How to define an enum in OpenAPI (Swagger)?

Does anyone know how to define possible enum values in an OpenAPI 2.0 definition so that they will be displayed in the Model tab of Swagger UI?
Example here has an enum option for the status property.
How to do define such an enum in OpenAPI 2.0?

Upvotes: 91

Views: 214276

Answers (4)

Ricardo Souza
Ricardo Souza

Reputation: 16446

Updating this with YAML syntax.

OpenAPI 2.0:

parameters:
  - in: query
    name: sample
    description: a sample parameter with an enum value
    type: string
    enum:
      - 1
      - 2
    required: true

OpenAPI 3.0:

parameters:
  - in: query
    name: sample
    description: a sample parameter with an enum value
    schema:
      type: string
      enum:
        - 1
        - 2
    required: true

Upvotes: 34

Ron
Ron

Reputation: 14810

"enum" works like this in OpenAPI 2.0:

      {
        "in": "query",
        "name": "sample",
        "description": "a sample parameter with an enum value",
        "type": "string",
        "enum": [ "1", "2"],
        "required": true
      }

and in OpenAPI 3.0:

      {
        "in": "query",
        "name": "sample",
        "description": "a sample parameter with an enum value",
        "schema": {
          "type": "string",
          "enum": [ "1", "2"]
        },
        "required": true
      }

As you can see, there's a query parameter called sample of type string, and has an enum stating two possible values. In this case, the sample states the parameter is required, so the UI will not show an empty value as an option.

For a minimal working sample, try this:

{
  "swagger": "2.0",
  "info": {
    "title": "title",
    "description": "descriptor",
    "version": "0.1"
  },
  "paths": {
    "/sample": {
      "post": {
        "description": "sample",
        "parameters": [
          {
            "in": "query",
            "name": "sample",
            "description": "a sample parameter with an enum value",
            "type": "string",
            "enum": [
              "1",
              "2"
            ],
            "required": true
          }
        ],
        "responses": {
          "200": {
            "description": "Successful request."
          }
        }
      }
    }
  }
}

To test it locally, you can declare a variable (for example spec) in your javascript, and pass it into the SwaggerUi object.

  var spec = { ... };

  window.swaggerUi = new SwaggerUi({
    url: url,
    spec: spec,
    dom_id: "swagger-ui-container",
    supportedSubmitMethods: ['get', 'post', 'put', 'delete'],
    onComplete: function(swaggerApi, swaggerUi){
    ...

The url parameter will be ignored in this case.

Eventually, the output looks like this:

enter image description here

Upvotes: 103

Eulalie367
Eulalie367

Reputation: 198

This isn't the exact answer, but it might work for you until they add this functionality.

Simply declare the property like so

"MyObject":{
   "properties":{
      "MyEnum":{
         "type":"Value1 or Value2 or Value3"
      }
   }
}

Your ModelSchema will show {}, but The Model will show MyEnum(Value1 or Value2 or Value3, optional)

Upvotes: -3

dstefanov
dstefanov

Reputation: 1

This should work:

{
    "name": "bookingType",
    "in": "path",
    "type": "array",
    "items": {
        "enum": [
            "packages", "accommodations"
        ]
    },
    "description": "lorem ipsum"
}

Reference https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#itemsObject

Upvotes: -2

Related Questions