Ask a Question

Swagger open API spec

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

  "alg": "HS256",

   "typ:" "JWT"




  "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.


Hey @NickDotIo. As you pointed out, there is native support in the OpenAPI syntax for describing JWTs:


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?
Showing results for 
Search instead for 
Did you mean: