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?
Add a comment
|
4 Answers
"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:
9 Comments
eloleon
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 - 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?
Ron
Which version of the UI to do use? When I tested it, it worked fine.
eloleon
I'm using version version 2.0.47 and trying to modify json in this example: github.com/swagger-api/swagger-ui/tree/master/dist. If you could modify this json: petstore.swagger.wordnik.com/v2/swagger.json and throw it somewhere online I'd appreciate it
Ron
You're looking at the wrong file. Check swagger-ui.js instead.
eloleon
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 ?
|
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
4 Comments
theberzi
Must it be of
type: string even if the values are integers?
Ricardo Souza
Nope. I defined the field as of type string in those examples, but you don't need to, if you would like them to be something else.
ka3ak
I've tried the second solution and still see "...String sample..." in generated code. It only works by me if I create an extra object for enum and refer to it
parameters: - $ref: '#/components/parameters/sample' looks like a bug to meRicardo Souza
@ka3ak could you share a minimal sample that reproduces your issue?
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
1 Comment
Ron
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.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)
1 Comment
Helen
This is not a valid syntax for
type in OpenAPI/Swagger.