Swagger open API spec

[NickDotIo]

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.

[joejoyce]

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?

[NickDotIo]

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.