I want to define enum in openAPI.
I looked at this post:
How to define an enum in OpenAPI (Swagger)?
and I want to be able to see the enum like:
I'm working with components and I define it as:
components:
schemas:
FilterImg:
type: object
properties:
name:
type: string
enum: ["img_1", "img_2"]
value:
type: string
And I'm using it:
post:
summary: Add new img
tags:
- img
description: Lets a user post a new img
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/FilterImg'
responses:
'200':
description: Successfully
But I can't see the enum as enum scroll menu (in the web browser), as we can see it in the example.
What am I missing ?
You are passing application/json in content type and you want enum dropdown how its possible?
You need to learn more about swagger from this documentation Swagger Docs and Openapi Specification,
Anyway i got an idea, you need this dropdown in body so here i have just added in application/x-www-form-urlencoded content type:
post:
summary: Add new img
tags:
- img
description: Lets a user post a new img
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/FilterImg'
responses:
'200':
description: Successfully
Remaining things will be same.
It will looks like:
In case of JSON/XML request and response bodies, the enum values for individual body fields are displayed in the schema documentation, that is on the Schema tab (or Model tab in case of OpenAPI 2.0).
Related
I have a problem with Swagger UI where it displays an empty "Examples" combobox (marked yellow on the image below) which does not look good. Is there a way to remove it or change its text to something useful?
I tried adding the example tag, but it won't work. The operation definition looks like this:
post:
tags:
- pet
summary: Add a new pet to the store
operationId: addPet
requestBody:
description: Pet object that needs to be added to the store
content:
application/json:
schema:
$ref: '#/components/schemas/Pet'
application/xml:
schema:
$ref: '#/components/schemas/Pet'
required: true
responses:
405:
description: Invalid input
content: {}
security:
- petstore_auth:
- write:pets
- read:pets
It was a bug in Swagger UI v. 3.23.0-3.23.1 (and Swagger Editor 3.6.31) that was fixed in v. 3.23.2.
I have a problem with Swagger UI where it displays an empty "Examples" combobox (marked yellow on the image below) which does not look good. Is there a way to remove it or change its text to something useful?
I tried adding the example tag, but it won't work. The operation definition looks like this:
post:
tags:
- pet
summary: Add a new pet to the store
operationId: addPet
requestBody:
description: Pet object that needs to be added to the store
content:
application/json:
schema:
$ref: '#/components/schemas/Pet'
application/xml:
schema:
$ref: '#/components/schemas/Pet'
required: true
responses:
405:
description: Invalid input
content: {}
security:
- petstore_auth:
- write:pets
- read:pets
It was a bug in Swagger UI v. 3.23.0-3.23.1 (and Swagger Editor 3.6.31) that was fixed in v. 3.23.2.
I am writing API documentation using OpenAPI 3.0. At the moment I have:
paths:
/script/update:
post:
tags:
- "Script"
summary: Update a script
operationId: updateScript
responses:
'200':
description: OK
"404":
description: Not Found
requestBody:
description: A script object in order to make the request
required: true
content:
application/x-www-form-urlencoded:
schema:
type: object
properties:
subsite_id:
type: string
script:
type: object
properties:
script:
$ref: '#/components/schemas/ScriptType'
type:
type: string
enum:
- custom
- interface
- freshbot
- feeder
- getter
- smcf
status:
$ref: '#/components/schemas/ScriptStatus'
comment:
type: string
format: string
reason:
type: string
format: string
To problem comes when I try to use to Swagger UI.
The only thing that appears is the following:
What I want is that the script object can be filled out field by field for each of the properties it has, like the subsite_id. What am I missing?
Swagger UI 3.x and 4.x do not have a form editor for JSON objects, so all JSON data needs to be entered in the JSON format: { "prop": value, ... }
Here's the corresponding feature request you can track:
https://github.com/swagger-api/swagger-ui/issues/2771
I'm looking for an elegant way to define an api that can consume JSON data as well as form data. The following snippet works, but it's not elegant and requires all kind of ugly code in the backend. Is there a better way to define this?
What works right now:
paths:
/pets:
post:
consumes:
- application/x-www-form-urlencoded
- application/json
parameters:
- name: nameFormData
in: formData
description: Updated name of the pet
required: false
type: string
- name: nameJSON
in: body
description: Updated name of the pet
required: false
type: string
Basic idea of how I'd like it to work:
paths:
/pets:
post:
consumes:
- application/x-www-form-urlencoded
- application/json
parameters:
- name: name
in:
- formData
- body
description: Updated name of the pet
required: true
type: string
But this doesn't work because the in value must be a string, not an array.
Any good ideas?
OpenAPI 2.0
In OpenAPI 2.0, there's no way to describe that. Form and body parameters are mutually exclusive, so an operation can have either form data OR JSON body but not both. A possible workaround is to have two separate endpoints - one for form data and another one for JSON - if that is acceptable in your scenario.
OpenAPI 3.0
Your scenario can be described using OpenAPI 3.0. The requestBody.content.<media-type> keyword is used to define various media types accepted by the operation, such as application/json and application/x-www-form-urlencoded, and their schemas. Media types can have the same schema or different schemas.
openapi: 3.0.0
...
paths:
/pets:
post:
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Pet'
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/Pet'
responses:
'200':
description: OK
components:
schemas:
Pet:
type: object
properties:
name:
type: string
description: Updated name of the pet
required:
- name
Further info:
OAS3: Describing Request Body
https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#support-for-x-www-form-urlencoded-request-bodies
https://blog.readme.io/an-example-filled-guide-to-swagger-3-2/#requestformat
I have a service that can have two different kind of body parameters based on the Content-Type header.
E.g. for path /Pet:
If Content-Type: application/somecustom.resource+json is used, then POST can take up Pet as the body parameter.
If Content-Type: application/somecustom.function+json is used, then POST should take up some different body parameter to invoke a function and return a different response.
Any suggestion on how to manifest this in OpenAPI (Swagger)?
OpenAPI 3.0 supports different schemas per media type.
openapi: 3.0.0
...
paths:
/pet:
post:
requestBody:
required: true
content:
application/somecustom.resource+json:
schema:
$ref: '#/components/schemas/Pet'
application/somecustom.function+json:
schema:
$ref: '#/components/schemas/Foo'
No, it's not possible to define a two different body parameters for the same operation, in the same path item. The path item name are unique by virtue of being property names (and therefore "keys" in the JSON key-value map), and Swagger specification allows at most one body parameter in a given operation.
There are a few alternative approaches to address this need:
Create two separate path items
For example:
/pets/createFromDescription:
post:
summary: Create a pet from a basic description
operationId: createPetFromDescription
parameters:
- name: petDescription
in: body
required: true
schema:
$ref: "#/definitions/PetDescriptionObject"
responses:
200:
description: OK
/pets/createFromCatalog:
post:
summary: Create a pet from a standard catalog entry
operationId: createPetFromCatalogEntry
parameters:
- name: petCatalogEntry
in: body
required: true
schema:
$ref: "#/definitions/PetCatalogEntry"
responses:
200:
description: OK
Create subtypes, with a discriminator
Described in the Swagger–OpenAPI 2.0 specification here.
Example:
/pets:
post:
summary: Create a pet
operationId: createPet
parameters:
- name: petSource
in: body
description: Structured pet information, from which to create the object
required: true
schema:
$ref: "#/definitions/CreatePet_Request"
responses:
200:
description: OK
definitions:
CreatePet_Request:
type: object
properties:
requestVariant:
type: string
required:
- requestVariant
discriminator: requestVariant
PetDescriptionObject:
allOf:
- $ref: "#/definitions/CreatePet_Request"
- type: object
properties:
name:
type: string
description:
type: string
PetCatalogEntry:
allOf:
- $ref: "#/definitions/CreatePet_Request"
- type: object
properties:
SKU:
type: string
Breed:
type: string
Comments:
type: string
Neither of these methods is keyed to the media type of the request. While your request may accept multiple media types, if the use of a particular media type implies some requirement about the request body, you'd have to document that in the description property of the operation or body parameter.