Defining responses in swagger is easy:
responses:
# Response code
200:
description: Successful response
schema:
title: OK
type: array
items:
title: Person
type: object
properties:
name:
type: string
single:
type: boolean
How I can return simple string and not an array
What if API endpoint makes a redirect, actually in my case redirecting is the successful attempt.
Let's skip the fact that redirecting in an API is a non-professional thing!
Update: Responding with a string is easy too:
description: A simple string response
schema:
type: string
Related
I'm currently trying to make an API doc page thanks to nelmio-api-bundle. I only have one route which is a POST route. I'm receiving a JSON in the body of the request and I'm using the Serializer from symfony to deserialize it in a DTO. I'm also using a DTO for the response (which contains the status code, a bool set to true or false, and a message). Now I'm trying to use these DTO (for input and output) to build the API documentation with nelmio-api-bundle but how to make it ? I'm using PHP8.1 attributes to make it, for response it almost works (except that the response is shows as an array) but I don't know how to make it for the inputs.
Here is my current code:
#[Route('/user', methods: ['POST'])]
#[OA\Parameter(
name: 'user',
description: 'The user information in JSON',
in: 'query',
required: true
)]
#[OA\Response(
response: 200,
description: 'Returns the success response',
content: new OA\JsonContent(
type: 'array',
items: new OA\Items(ref: new Model(type: SuccessResponseDTO::class))
)
)]
public function registerUser(Request $request, LoggerInterface $logger): JsonResponse
{
//the code to register the user
}
And here is the result:
Do someone know how to make it ?
I get this syntax error, while I'm using the traits two times in the resource(one in the header part and another one is in the response part),I'm trying to fix it, but unable to do it.
error is :
is:
-Responsemessage
Hence below is the RAML specification.
#%RAML 1.0
title: RAML_Project
traits:
Responsemessage:
responses:
200:
body:
application/json:
example: {"Statuscode": 1,"message" :"Success done by traits "}
client-id-required:
headers:
client_id:
type: string
required: true
secret_key:
required: true
type: string
/QueryActivity:
get:
is:
- client-id-required
queryParameters:
Fistname:
type: string
required: true
is:
-Responsemessage
/QuerybyEmpid:
get:
body:
application/json:
type: !include dataType.raml
is:
- Responsemessage
-Responsemessage is missing the space between the - and the R. Also you seem to have 2 is: facets in the same resource. Thie - is the YAML array notation. I recommend to instead use the simpler array notation with [] instead:
/QueryActivity:
get:
is: [client-id-required, Responsemessage]
queryParameters:
Fistname:
type: string
required: true
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.
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