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.
Related
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).
Since keys of the object that my response returns are dynamic, i used additionalProperties to make them as such. While on the ui of the editor it shows properly, when i use code gen into html the response is missing fields. This is just one example, there are also similar components which are not rendered properly.
// my path
/cmc/assets:
get:
summary: Details of each currency available
operationId: Get market assets
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/MarketAsset'
'400':
$ref: '#/components/responses/400'
'404':
$ref: '#/components/responses/404'
'500':
$ref: '#/components/responses/500'
// component that the 200 response refers to
MarketAsset:
type: object
additionalProperties:
type: object
properties:
name:
type: string
example: "Purpose"
unified_cryptoasset_id:
$ref: '#/components/schemas/PositiveStringInteger'
can_withdraw:
$ref: '#/components/schemas/StringTrueOrFalse'
can_deposit:
$ref: '#/components/schemas/StringTrueOrFalse'
min_withdraw:
$ref: '#/components/schemas/PositiveStringFloatOrInt'
max_withdraw:
$ref: '#/components/schemas/PositiveStringFloatOrInt'
maker_fee:
$ref: '#/components/schemas/PositiveStringFloatOrInt'
taker_fee:
$ref: '#/components/schemas/PositiveStringFloatOrInt'
example:
name: "Purpose"
unified_cryptoasset_id: "101"
can_withdraw: "true"
can_deposit: "false"
min_withdraw: "100"
max_withdraw: "1000"
maker_fee: "0"
taker_fee: "0"
In the editor:
The html ui:
I have tried both with and without examples but the result is the same, the editor ui works fine while generated html doesn't seem to work.
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.
My server application sends json response in the following format
{
result: ... //this could be success or error
additional-info: ... //this is a wrapper and could contains information depending the the operation
}
additional-info could be a success message (eg "operation successful"), error message (eg "operation failed") or say an object in string format (eg {user-name: manu}.
I have created swagger definition of the above object as follows:
ServerSuccessResponse:
type: object
properties:
result:
type: string
enum:
- success
additional-info:
type: string
enum:
- SuccessMessages
- UserResponse
required:
- result
- additional-info
ServerFailureResponse:
type: object
properties:
result:
type: string
enum:
- error
additional-info:
type: string
enum:
- FailureMessages
Then I am trying to use the above definition in APIs as follows
/user/username:
post:
tags:
- new user
summary: Add a new user to the database
description: Use this path to add a new user
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/NewUser'
responses:
'200':
description: means the user was added successfully
content:
application/json:
schema:
$ref: '#/components/schemas/ServerSuccessResponse'#BUT ITS NOT CLEAR WHAT ADDITIONAL-INFO CONTAINS
'404':
description: >-
Only a signed in user can add a question. This response means that
the user isn't signed in.
content:
application/json:
schema:
$ref: '#/components/schemas/ServerFailureResponse' #BUT ITS NOT CLEAR WHAT ADDITIONAL-INFO CONTAINS
'500':
description: >-
means some internal error occur on the server while doing the
operation. The state of the operation if un-determined and the
operation could be successful, failed or partially successful
(because some database operations are not rolled back if error
occurs!
content:
application/json:
schema:
$ref: '#/components/schemas/ServerFailureResponse'#BUT ITS NOT CLEAR WHAT ADDITIONAL-INFO CONTAINS
My issue is that at the moment, ServerFailureResponse or ServerSuccessResponse doesn't tell what additional-info would contain. I would like to redesign the API definition such that what is contained in the additional-info also gets clear. Is there a way I could do it? In code, I still want to use additional-info as wrapper. I only want that in Swagger, the content of additional-info is clear for each response.
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