Ask a Question

Swagger open API spec

NickDotIo
New Contributor

Swagger open API spec

Hello all,

 

I have an API I've defined with swagger that has a custom JWT format. I'd like to tell my API clients what the format is so that they can include it in an HTTP header. I can do this manually in the API description tag. Example:
JWT format
Header
{

  "alg": "HS256",

   "typ:" "JWT"

}

Payload

{

  "myPayload": "MyData"

}

 

But in order to be formatted this way, I need to describe it like this: <p> JWT format<p> Header<br>{<br>&nbsp; "alg"&#58; "HS256", <br>&nbsp; "typ"&#58; "JWT"<br>}<br>Payload<br>{ <br> &nbsp; "myPayload"&#58; "my data"<br>}


Is there a better way that uses the proper swagger/yaml tags to do this? I know of the security schema tags but these don't let me describe my JWT format very well.

2 REPLIES 2
joejoyce
Staff

Hey @NickDotIo. As you pointed out, there is native support in the OpenAPI syntax for describing JWTs: https://swagger.io/docs/specification/authentication/bearer-authentication/

 

Is there a reason you cant use this approach?

The security schema tags communicate that an authorization bearer JWT is required but doesn't let me describe its structure. I have a custom JWT that I would like to document using open API tags. Are there any specific tags I can use or am I limited to only using the generic, free-form description tag?
 
Thanks.
cancel
Showing results for 
Search instead for 
Did you mean: