I am creating an API-Documentation in Swagger. I directly tried openapi 3.0. I somehow cannot get the description for my request body to work.
requestBody:
content:
application/x-www-form-urlencoded:
schema:
type: object
properties:
name:
description: The username of the user to be registered.
type: string
email:
description: The E-Mail address of the user to be registered.
type: string
password:
description: The password of the user to be registered.
type: string
required:
- name
- email
- password
But the descriptions won't show up:
I want to get something like Swagger 2 was generating. Below is how the same code converted to Swagger 2
This issue was fixed in Swagger UI 3.18.2.
Related
I'm new in the world of API. I want to do an API using swagger in yaml. My teacher given us a snippet of code that should simulate a login API, but Bearer style. I want to map the generated identifier with the correlated name
paths:
/session:
post:
tags: ["login"]
summary: Logs in the user
description: |-
If the user does not exist, it will be created,
and an identifier is returned.
If the user exists, the user identifier is returned.
operationId: doLogin
requestBody:
description: User details
content:
application/json:
schema:
type: object
properties:
name:
type: string
example: Jason
pattern: 'ˆ.*?$'
minLength: 3
maxLength: 16
required: true
responses:
'201':
description: User log-in action successfully
content:
application/json:
schema:
type: object
properties:
identifier:
# change here if you decide to use an integer
# or any other type of identifier
type: string
example: "abcdef012345"
/session/{identifier}:
get:
summary: Get username
description: Get username from identifier
operationId: getUsername
parameters:
- name: identifier
in: path
description: User ID
required: true
schema:
$ref: "#/components/schemas/User/properties/identifier"
responses:
'200':
description: 'User exists'
content:
application/json:
schema:
$ref: "#/components/schemas/User"
components:
schemas:
User:
type: object
properties:
identifier:
type: string
example: "abcdef012345"
name:
type: string
example: "Jason"
I tried adding the "/session/{identifier}" path, but the get never retrieve the correct information. How can I do it?
Thank you in advance
Is it possible to assign a customised name to a Components object in OpenAPI?
I currently have two Component objects that specify a request schema:
Request1:
type: object
description: Request 1
properties:
a:
description: Filter 1 a
$ref: '#/definitions/Filter1a'
b:
description: Filter 1 b.
$ref: '#/definitions/Filter1b'
Request2:
type: object
description: Request 2
properties:
query:
type: object
description: Filter 2.
properties:
bool:
type: object
properties:
must:
type: array
items:
type: object
properties:
match_all:
type: object
In the endpoint description I refer to these schemas as follows:
/v2/myEndpoint:
post:
tags:
- some tags
operationId: someId
summary: Some summary
description: Some description
produces:
- application/json
parameters:
- in: body
name: body
required: false
schema:
oneOf:
- $ref: '#/definitions/Request1'
- $ref: '#/definitions/Request2'
When I publish the yaml file, the UI shows Request1 and Request2 in selection tabs, which carry the names 'Request1' and 'Request2'. Is it possible to assign custom names to them, so that the UI will show the custom names instead? For example 'Custom name request 1' and 'Custom name request 2'?
Many thanks!
I assume you meant Swagger UI.
title would do that. Link to Open Api Spec.
Request1:
title: Custom name request 1
type:...
Request2:
title: Custom name request 2
type:...
I am using OpenApi do document an API, i have a path /Login which lets me specify Username and Password as parameters and returns a Bearer style JWT in the "authorization" header in the response.
For further use in the API this JWT is used with the "Authorize" mechanism so the other paths can be accessed.
Sadly the authorization header is only visible if i open the network tracing in my browser.
Therefore my question, can i somehow tweak my OpenAPI YAML so the value is displayed and can then be copy/pasted to the authorization for the rest of the API. I am using the latest swagger editor (https://editor.swagger.io/)
This is what i have specified
paths:
/Login:
post:
servers:
- url: ....
description: Local test server
tags:
- Login
summary: Logs into the API and returns the authorization.
description: Username and Password are passed in header
security: []
#- bearerAuth: []
parameters:
- $ref: '#/components/parameters/Username'
- $ref: '#/components/parameters/Password'
responses:
200:
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/Login'
headers:
authorization:
$ref: '#/components/headers/authorization'
parameters:
Username:
name: Username
in: header
description: Username to authorize with
schema:
type: string
Password:
name: Password
in: header
description: Password to authorize with
schema:
type: string
headers:
authorization:
schema:
type: string
description: Authorization token.
I am writing API Document by Swagger.
I defined the Response format is:
definitions:
ResponseFormat:
type: object
properties:
name:
type: string
msg:
type: string
description: Error or success message
data:
type: object
Then, for each API, the format of data (object) will change. How can I change it.
Thank you!
I'm defining a resource that you POST to with a non-JSON body. It's just a string like form parameters. Something like what happens with OAuth:
grant_type=&code=&redirect_uri=
How can I document that on Swagger? Do I have to use formParam format instead of body? Everything I put into body it converts to JSON examples.
TokenRequest:
properties:
grant_type:
type: string
description: OAuth Grant Type
enum:
- authorization_code
- refresh
code:
type: string
description: Authorization Code obtained from /authorize required if grant_type = au
redirect_uri:
type: string
description: Defined Redirect URI Example - https://example.com/callback
refresh_token:
type: string
description: Required if grant_type = refresh
Here is an example on how to document the form data:
post:
tags:
- pet
summary: Updates a pet in the store with form data
description: ''
operationId: updatePetWithForm
consumes:
- application/x-www-form-urlencoded
produces:
- application/xml
- application/json
parameters:
- name: petId
in: path
description: ID of pet that needs to be updated
required: true
type: integer
format: int64
- name: name
in: formData
description: Updated name of the pet
required: false
type: string
- name: status
in: formData
description: Updated status of the pet
required: false
type: string
responses:
'405':
description: Invalid input
security:
- petstore_auth:
- 'write:pets'
- 'read:pets'
But in your case, it seems you want to define OAuth setting so please refer to Swagger Spec 2.0 for more information. Here is an example for PetStore:
securityDefinitions:
petstore_auth:
type: oauth2
authorizationUrl: 'http://petstore.swagger.io/api/oauth/dialog'
flow: implicit
scopes:
'write:pets': modify pets in your account
'read:pets': read your pets
api_key:
type: apiKey
name: api_key
in: header