Context
JSON Schema does not support description/titles on enums. Therefore the recommended work-around is to use oneOf syntax with an array of constants, which does support descriptions.
Current Behavior
Although the description or title displays, the const does not. This is really a bug because you can't easily see what value you are expected to use. See below:
Expected Behavior
My recommendation on non-object oneOfs would be to treat them visually just like enums and display the possible values along with their descriptions. The drop-down is valuable for more complex situations like objects, but nonsensical for what should be simple enums but for the JSON schema limitation.
Sample Doc
Here is a sample OpenAPI 3.1 document demonstrating the issue:
{ "openapi": "3.1.0", "info": { "title": "Dog Food API", "version": "1.0.0", "description": "API for adding dog food SKUs" }, "paths": { "/addDogFood": { "post": { "operationId": "addDogFood", "summary": "Add dog food items", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "dogFoods": { "type": "array", "items": { "type": "object", "properties": { "sku": { "type": "string" }, "name": { "type": "string", "readOnly": true }, "flavor": { "type": "string", "oneOf": [ { "const": "beef", "title": "Beef-flavored" }, { "const": "chicken", "title": "Chicken-flavored" }, { "const": "fish", "title": "Fish or other seafood flavored" } ] } }, "required": [ "sku", "name", "flavor" ] }, "uniqueItems": true, "minItems": 1 } }, "required": [ "dogFoods" ] } } } }, "responses": { "200": { "description": "Dog food items added successfully" } } } } } }
Context
JSON Schema does not support description/titles on enums. Therefore the recommended work-around is to use oneOf syntax with an array of constants, which does support descriptions.
Current Behavior
Although the description or title displays, the const does not. This is really a bug because you can't easily see what value you are expected to use. See below:
Expected Behavior
My recommendation on non-object oneOfs would be to treat them visually just like enums and display the possible values along with their descriptions. The drop-down is valuable for more complex situations like objects, but nonsensical for what should be simple enums but for the JSON schema limitation.
Sample Doc
Here is a sample OpenAPI 3.1 document demonstrating the issue:
{ "openapi": "3.1.0", "info": { "title": "Dog Food API", "version": "1.0.0", "description": "API for adding dog food SKUs" }, "paths": { "/addDogFood": { "post": { "operationId": "addDogFood", "summary": "Add dog food items", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "dogFoods": { "type": "array", "items": { "type": "object", "properties": { "sku": { "type": "string" }, "name": { "type": "string", "readOnly": true }, "flavor": { "type": "string", "oneOf": [ { "const": "beef", "title": "Beef-flavored" }, { "const": "chicken", "title": "Chicken-flavored" }, { "const": "fish", "title": "Fish or other seafood flavored" } ] } }, "required": [ "sku", "name", "flavor" ] }, "uniqueItems": true, "minItems": 1 } }, "required": [ "dogFoods" ] } } } }, "responses": { "200": { "description": "Dog food items added successfully" } } } } } }