80

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?

Hakan Fıstık
  • 16,800
  • 14
  • 110
  • 131
eloleon
  • 1,144
  • 2
  • 10
  • 18

4 Answers4

94

"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

Helen
  • 87,344
  • 17
  • 243
  • 314
Ron
  • 14,160
  • 3
  • 52
  • 39
  • Hi webron. Thanks for your suggestion. Still no joy with it... No matter what I try, I still can't get that nice output with all possible strings as in 'status' for addPet in example mentioned in question. Since I'm following same JSON schema as per this demo json - http://petstore.swagger.wordnik.com/v2/swagger.json - could you tell me how should I modify Pet definition for status to achieve same result as online demo? – eloleon Jan 05 '15 at 08:43
  • Which version of the UI to do use? When I tested it, it worked fine. – Ron Jan 05 '15 at 09:19
  • I'm using version version 2.0.47 and trying to modify json in this example: https://github.com/swagger-api/swagger-ui/tree/master/dist. If you could modify this json: http://petstore.swagger.wordnik.com/v2/swagger.json and throw it somewhere online I'd appreciate it – eloleon Jan 05 '15 at 09:33
  • You're looking at the wrong file. Check swagger-ui.js instead. – Ron Jan 05 '15 at 09:50
  • My bad - version is 2.1.0-alpha.7 which seems to be the latest. Are you able to define enum in that github example ? – eloleon Jan 05 '15 at 10:02
  • I've edited the answer. Let me know if it helps. If you need a sample with the pet store, I can do that as well. – Ron Jan 05 '15 at 10:20
  • Thanks webron. It is not what we hope to get. Example with possible enum values in Model that is available in demo is much nicer. thanks for your effort anyway – eloleon Jan 05 '15 at 10:59
  • Okay, I looked at the edit you suggested, and now the question is clearer (probably would have been better to edit the original question and specifically mention it relates to models). In any case, this is indeed a regression in the UI and to solve it, you should open an issue on the swagger-ui repository. – Ron Jan 05 '15 at 11:11
  • Thanks webron for all you help! – eloleon Jan 05 '15 at 11:15
31

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
Helen
  • 87,344
  • 17
  • 243
  • 314
Ricardo Souza
  • 16,030
  • 6
  • 37
  • 69
-2

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

dstefanov
  • 1
  • 6
    That's actually not a valid definition. The "items" object *has* to have a "type" property in it to be valid. In your example, `"type": "string"` would be fitting. – Ron Dec 31 '14 at 13:02
-3

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)

Eulalie367
  • 198
  • 4
  • 17