Best Practice to add JSON Web Token (JWT) into Swagger Documentation

[fr...@adsquare.com]

Hi together,

we protect our REST API with a JWT Token. The first step is to POST username and password as JSON to /login method, you then retrieve the Token as answer. We do not put any roles/rights into that token, we just use it for authentication. Roles are requested from the Backend via /user/current afterwards. We do it this way, as we do not want to transmit all Roles all the time between the client and the server = keeping the payload small.

I am wondering, what would be the best approach to document our API via Swagger for our JWT approach. As I understand there are just two types "API Key" and "Oauth2", both of them do not really fit it seems, as for example we do not have a typic oauth token url.

Any suggestions?

My goals:

* Document our API so that users can see, that a specific method is protected or not

* Enable the user to login/generate token via SwaggerUI.

Best

fri

[Ron Ratovsky]

There is no official support for JWT in Swagger.

https://github.com/swagger-api/swagger-ui/issues/818

--
You received this message because you are subscribed to the Google Groups "Swagger" group.
To unsubscribe from this group and stop receiving emails from it, send an email to swagger-swaggers...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

--

-----------------------------------------

http://swagger.io
https://twitter.com/SwaggerApi
-----------------------------------------

[David Feinzeig]

How did you end up solving this?  I have a similar need.

[tony tam]

It seems that you could easily create a page to do the login to get a token, and then use that in the api key authorization, which can be for any header name.  But as Ron said, JWT is not a formally supported scheme.  Passing arbitrary headers is, though.

[Steve Dearborn]

I don't know if you solved this already but here it goes.

If you are passing the JWT as part of a REST API request, then I would recommend using the Authorization header.  OAuth utilizes a BEARER token scheme and the good news is that Swagger 2.0 supports this.  It also supports BASIC but this does not semantically fit your use-case.  Others such as HOLER-OF-KEY (HOK) are not implemented in Swagger - yet.

In general, APIs can be protected by BASIC AUTH and OAUTH, or some proprietary method.  I also use API_KEY in header for trial-use APIs and so your JWT and be just copy & paste in API_KEY, especially if your APIs are transmitted over HTTPS/TLS with Strict-Transport-Security [header] enabled.

On Tuesday, September 1, 2015 at 8:16:08 AM UTC-4, fr...@adsquare.com wrote: