How do I describe a JWT sent in a response body in OpenAPI 3?

Question

According to the JWT introduction on jwt.io,

the output is three Base64-URL strings separated by dots that can be easily passed in HTML and HTTP environments."

I'm trying to figure out how to describe this in the schema of the response. I'm getting tripped up because it seems to me that "three strings separated by dots" is itself a string - would that be right?

Would the content section look like this?

content:
  text/plain:
    schema:
      type: string

In the OpenAPI docs, I see how to describe the bearer authentication in the components/securitySchemes section, but I think that has to do with the global/path operation security section, and not for the login method when the server sends the JWT to the client.

Answer 1

you can try something like this... (from https://json-schema.org/draft/2020-12/json-schema-validation.html#rfc.section.8.6)

{
"type": "string",
"format": "application/jwt",
"Schema": {
    "type": "array",
    "minItems": 2,
    "prefixItems": [
        {
            "const": {
                "typ": "JWT",
                "alg": "HS256"
            }
        },
        {
            "type": "object",
            "required": ["iss", "exp"],
            "properties": {
                "iss": {"type": "string"},
                "exp": {"type": "integer"}
            }
        }
    ]
}

}

but it presents the token before the base64url encoding.

so I prefer to write in the next form:

json_web_token:
  description: |
    JWT is built in the following format:
      f"base64urlEncoding(header) + '.' + base64urlEncoding(payload) + '.' + base64urlEncoding(signature)"
    header is an object containing -> {"alg": {CHOSEN_ALG}, "typ": "JWT"}
    payload is an object containing the claims (data of jwt)
    signature is an encoded with a PRIVATE_KEY object by our CHOSEN_ALG from the following format: 
      CHOSEN_ALG( PRIVATE_KEY, base64urlEncoding(header) + '.' + base64urlEncoding(payload))
  type: string
  format: application/jwt
  pattern: ^([a-zA-Z0-9_=]+)\.([a-zA-Z0-9_=]+)\.([a-zA-Z0-9_\-\+\/=]+)$
  example: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c"

Answer 2

You can use text/plain and add a description or you can use an application/jwt media type. Or both :-)

responses:
    '200':
      description: a JSON web token (JWT) required to login.
      content:
        application/jwt:
          schema:
            type: string