I have the following yaml
/orgs:
post:
produces: ['application/json']
consumes: ['application/json']
parameters:
- in: query
name: newKey
type: boolean
- in: body
name: org
required: true
schema:
$ref: '#/definitions/Org'
responses:
201:
schema:
$ref: '#/definitions/Org'
In the "Try This" form in the editor, the preview of the POST looks correct (the JSON is in the post body, and the content-type is correct):
[
But when I hit the "Send Request" button, it seems to throw the JSON in as a url-encoded string and not send the body.
I cloned the swagger-editor today, built it and put it in my server to host it locally and try out the API I am building.
Why is it sending the body as a url-encoded string?
For that specific path and request method you have to set Content-Type = "multipart/form-data"
This ended up being an issue in swagger editor that was resolved in a github issue. I realize it's frowned upon to post links to solutions, but I'm not going to copy the whole thread here.
Related
This question already has an answer here:
Sending cookie session id with Swagger 3.0
(1 answer)
Closed 1 year ago.
I built an API that uses CSRF-Cookies for authentification. Now I want to document this API using OpenAPI/Swagger.
All routes are protected by a middleware that verifies the CSRF-Token, except for /sanctum/csrf-cookie , which is used to initially retrieve the Token.
Therefore, I need the Swagger-UI to include the cookie on each request. I followed the documentation, but it does not work.
Here's an excerpt from my Swagger-Definition:
security:
- cookieAuth: []
paths:
/sanctum/csrf-cookie:
get:
operationId: "getApiToken"
responses:
'204':
description: "successful token retrieval"
headers:
Set-Cookie:
schema:
type: string
/login:
post:
operationId: "loginUser"
requestBody:
content:
application/json:
schema:
type: "object"
properties:
username:
type: string
password:
type: string
components:
securitySchemes:
cookieAuth:
type: apiKey
in: cookie
name: XSRF-TOKEN
As seen in the screenshot of my browsers network monitor, the headers of login request do not contain the XSRF-Token.
In Contrast, this is the exact same request sent by my frontend:
It should be shown in the authorize (lock) icon on the top right corner of the rendered swagger document.
In contrast you can add it to each request by adding the
security:
- api_key: []
block to each route definition. In that case the lock icon on the left side of the request panel in swagger ui should show the information. If you need to see them as headers make sure to add it to the route using a parameters block.
In some documents it says it allows this:
parameters:
- name: body
'in': 'body'
required: true
schema:
type: string
But in reality, the in argument can only be path, query, cookie or header.
I also could not skip the parameters, because it would generate the wrong rust code.
Yes! As described in the docs, here (under 'Primitive Body'):
https://swagger.io/docs/specification/2-0/describing-request-body/
In your swagger.yml you can specify it like so:
paths:
/status:
post:
summary: Updates the status message.
consumes:
- text/plain # <----------
parameters:
- in: body
name: status
required: true
schema:
type: string # <----------
responses:
200:
description: Success!
This is the exact code snipped from the docs, pasted here for your convenience. :)
No I don't think there is any way you can make the request body object part of your parameter object anymore, but you could skip your parameters with:
parameters: []
I'm trying to set two different responses of 302 in out API since our API redirects to a different Endpoint depending on the request sent. I'm current using Open API ver 3.0.1. How do I do that?
I basically just want two different Location Headers for the 302
redirect describing how why the particular Location header is returned. Or have two same 302 response codes
I was following this older thread. But it doesn't correctly reference the two different Location headers in the actual API Endpoint, and instead just shows a blank Location header.
My Code snippet is:
responses:
'200':
description: 'Sample 200 Response'
'302':
description: 'Sample 302 Responses. See <302ExpiredRefreshTokenstring> & <302ExpiredUserRefreshTokenstring> schemas for reference'
headers:
Location:
schema:
oneOf:
- $ref: '#/components/schemas/302ExpiredRefreshToken'
- $ref: '#/components/schemas/302ExpiredUserRefreshToken'
And the schema is:
components:
schemas:
302ExpiredRefreshToken:
type: string
example: 'www.<UIEndpoint>/ref-login?SessionId=d3fe5c6959ae0ce502d6027a7693c3ebe4543f51a878d60004e1331723fc0187&redirect_uri=https://www.lazada.com.ph&state=sample_state_54321&refresh_token=sCY2O0kev5Ic516A1INnQwRc8D1hbuOJ&BillerCode=00494&UserId=JBC_28'
description: Redirect URI if Refresh Token (FinTech) has already expired.
302ExpiredUserRefreshToken:
type: string
example: 'www.<UIEndpoint>/cpw-login?SessionId=d3fe5c6959ae0ce502d6027a7693c3ebe4543f51a878d60004e1331723fc0187&redirect_uri=https://www.lazada.com.ph&state=sample_state_54321&refresh_token=sCY2O0kev5Ic516A1INnQwRc8D1hbuOJ&BillerCode=00494&UserId=JBC_28'
description: Redirect URI if User Refresh Token (DigiFi) has already expired. This could be triggered even if the Refresh Token (FinTech) has not expired yet.
Adding multiple examples doesn't work either as it doesn't show the multiple examples, instead it's just a blank
headers:
Location:
schema:
type: string
examples:
'test1':
value: 'value1'
'test2':
value: 'value2'
description: 'Description of Location Header'
But the Multiple examples for a header work when placed on the request paramters as I added examples in the request like this.
parameters:
name: Location
in: header
examples:
test1:
value: 'value2'
summary: 'summary 1'
test2:
value: 'value 1'
summary: 'summary 2'
There's no need for multiple schemas for the Location header because the data type is the same in both cases - type: string. Instead, add multiple examples of the header value:
responses:
...
'302':
description: Some token has expired... Clients should follow the `Location` header to refresh the token.
headers:
Location:
description: URI where the client can refresh the expired token.
schema:
type: string
format: uri # Optional - use if the Location header is an absolute URI, starting with http(s)://
examples:
302ExpiredRefreshToken:
description: Redirect URI if Refresh Token (FinTech) has already expired
value: 'www.<UIEndpoint>/ref-login?SessionId=d3fe5c6959ae0ce502d6027a7693c3ebe4543f51a878d60004e1331723fc0187&redirect_uri=https://www.lazada.com.ph&state=sample_state_54321&refresh_token=sCY2O0kev5Ic516A1INnQwRc8D1hbuOJ&BillerCode=00494&UserId=JBC_28'
302ExpiredUserRefreshToken:
description: >-
Redirect URI if User Refresh Token (DigiFi) has already expired.
This could be triggered even if the Refresh Token (FinTech) has not expired yet.
value: 'www.<UIEndpoint>/cpw-login?SessionId=d3fe5c6959ae0ce502d6027a7693c3ebe4543f51a878d60004e1331723fc0187&redirect_uri=https://www.lazada.com.ph&state=sample_state_54321&refresh_token=sCY2O0kev5Ic516A1INnQwRc8D1hbuOJ&BillerCode=00494&UserId=JBC_28'
But since you use Swagger UI, please note that it currently does not display examples in response headers. Follow this issue for updates: https://github.com/swagger-api/swagger-ui/issues/5432
I'm trying to generate client code with swagger-codegen from a Micronaut server. The problem arises with authenticated POST and PUT routes (it works fine for GET an DELETE).
When I have a method like this in a controller:
#Override
#Post("/")
public Single<? extends HttpResponse> updateStatus(Authentication authentication, GameReference gameReference) {
// ...
}
The resulting swagger for that method looks like this:
post:
tags:
- /presence
description: Updates status
operationId: updateStatus
parameters: []
requestBody:
content:
application/json:
schema:
type: object
properties:
authentication:
$ref: '#/components/schemas/Authentication'
gameReference:
$ref: '#/components/schemas/GameReference'
required: true
responses:
default:
description: HTTP 204 for successful updates.
content:
application/json: {}
So the Authentication Principal has been built into the request body and in generated client code the parameters to that method would be an object with both Authentication and GameReference.
What I have tried to work around this problem:
Add #Parameter(hidden = true) before Authentication parameter. Did not change anything.
Playing around with swagger annotations for authentication, like #SecuritySchema and #SecurityDefention. Authentication Principle still gets generated into the swagger yaml.
Is this a bug in Micronauts Swagger implementation or is there a way to work-around this? Note that this works well for GET and DELETE. There the Authentication Principle is ignored.
It was accepted as a bug by the Micronaut team:
https://github.com/micronaut-projects/micronaut-core/issues/1155
I have an API call which responds 200 OK and returns an HTML. I would like to add this to my API documentation
(especially since i validate it using dredd and unless i provide it with the expected response body the test fails). How
would i do this in Swagger?
--- More details ---
My Response to an API call is 200 OK and with a one line Response Body:
<html><body>You are being redirected.</body></html>
I can easily define the Response Body in Blueprint in the following form:
+ Response 302 (text/html; charset=utf-8)
+ Body
`<html><body>You are being redirected.</body></html>`
But i'm not sure how to do this in Swagger. Almost all examples i can find are for application/json responses (understandably) and i'm having trouble
guessing the correct syntax for this kind of response.
The relevant swagger text in my document is this (so far without specifying the response body, so with an empty body dredd
fails because the response body should be <html><body>You are being redirected.</body></html>):
# this is my API spec in YAML
swagger: '2.0'
info:
title: My API (Swagger)
description: blablabla
version: "1.0.0"
# the domain of the service
host: my.domain.com
# array of all schemes that your API supports
schemes:
- https
# will be prefixed to all paths
basePath: /
produces:
- application/json; charset=utf-8
paths:
/users/password:
post:
summary: Password Reset
description: |
Handles Reset password for existing user.
consumes:
- application/x-www-form-urlencoded
produces:
- text/html; charset=utf-8
parameters:
- name: "user[email]"
description: email
in: formData
required: true
type: string
default: "user#gmail.com"
tags:
- Reset Password
responses:
200:
description: Success
Please comment if you have any suggestions on this. Thanks!
Figured it out. the response object has a field called "examples" which allows to show examples to your API response.
The syntax is clearly shown in the specification and basically says you need to identify the MIME-type for the example response, in my case text/html and the value is the actual text.
so like this:
responses:
200:
description: success and returns some html text
examples:
text/html:
<html><body>Your HTML text</body></html>
That's it. Now whether or not dredd knows to take this value and compare it is another story. their docs state that any response other than JSON is validated as plain text so this should work.
Hope this helped.
In case someone needs this in the openapi version 3.0 you can do it this way:
Save your HTML. For example give this at the end of your file:
components:
schemas:
error401:
type: string
example: '<html>HTML text</html>'
Then you can reference this scheme in responses wherever you want. For example:
responses:
'401':
description: Error
content:
text/html:
schema:
$ref: '#/components/schemas/error401'