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
Related
My spec is as below.
/path:
/user:
get:
parameters:
- name: Authorization
in: header
required: true
schema:
type: string
Problem is that it is giving me the below warning. I get the same warning if I add Content-Type or Accept header.
Header parameters named Authorization are ignored. Use securitySchemes and security to define the Authorization
I tried the below but I don't see Authorization header added in the request. I am using https://editor.swagger.io to create the spec.
/path:
/user:
get:
parameters:
- name: Authorization
in: header
required: true
schema:
type: string
security:
- my_auth: []
components:
securitySchemes:
my_auth:
type: http
scheme: bearer
bearerFormat: JWT
Any help is appreciated. Thanks !!
In the request parameters, there are operation's specific parameters.
The general purpose HTTP headers aren't defined here because:
Content-Type is defined by the request body content. If there are multiple content types, the consumer has to choose and set Content-Type accordingly.
Accept is similar; it only relates to the response message.
For security, we do not describe the Authorization header but instead define the security scheme (see docs for more).
You may use the description property to explain how to use these headers with your API. However, if your API follows standards, it should not be necessary.
Once you have added the security schema to your API definition, you can use the Authorization function of Swagger Editor. So, you will add your token and trigger "Try it out." Swagger will populate the Authorization header; see the attached screenshot.
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.
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 introducing an optional "query parameter" (with default value) for one of my API endpoint ( i.e. /foo2) but hoping that existing API consumers don't have to make any changes in their application when they regenerate the java client stub from the new swagger file.
I was expecting that the generated java client will offer overloaded methods, to operate with and without a method parameter, so that my existing API consumers can work without any changes to their call. At the same time, they can switch to its more generic offering.
public void foo2Get() throws ApiException {
public void foo2Get(String type) throws ApiException {
But it generates ONLY the latter. I don't see the former.
At the same time, generated python client from same swagger throws a var arg and this way it more flexible and hence old and new offerings will work without any issues.
def foo2_get(self, **kwargs):
(swagger sample used: attached)
** Description**
Is there a way to overcome this limitation with java code generator.
swagger-generator version
swagger 2.0
Swagger declaration file content or url
swagger: '2.0'
info:
title: identity
version: Unknown
consumes:
- application/json
produces:
- application/json
parameters:
typeParam:
name: type
in: query
required: false
allowEmptyValue: true
default: basic
type: string
enum:
- basic
- advanced
paths:
/foo2:
get:
consumes:
- application/json
parameters:
- "$ref": "#/parameters/typeParam"
responses:
'200':
description: OK
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'