Best pattern/practice to describe a JWT token content on SwaggerHub

[HenrikHL]

I have a field called envelope which is a JWT token expressed as a String.

What would be the best practice to describe the contents of this token? Has anybody tried this?

components:
  schemas:
    envelope:
      type: string
      maxLength: 1500
      description: 'A JWT token'
      example: 'xxxxx.yyyyy.zzzzz'

I would like to describe the payload of the token - e.g.:

{
  "name": "John Doe",
  "admin": true
}

 I cannot find any examples of this...

[frankkilcommins]

Hi @HenrikHL ,

You could consider to describe the payload claims using markdown in the description and present either as a JSON example or as a table (or indeed both).

Example:

    envelope:
      type: string
      maxLength: 1500
      description: |
        A JWT token (_header_._payload_._signature_) with the following `payload` claims structure:
        ```
        {
          "name": "John Doe",
          "admin": true
        }
        ```
        Claims Details:
        
        |Claim|Type|Example|
        |-----|----|-------|
        |name|`string`|"John Doe"|
        |admin|`boolean`|true|
        
        
      example: 'xxxxx.yyyyy.zzzzz'  

Hope this helps.

[HenrikHL]

Thank you @frankkilcommins - this is very helpful and for sure a valid way to do it.

I also investigated a little more - another way to do it would be to create an unused Definition - e.g. payload:

    payload:
      type: object
      description: `payload` claims structure
      allOf:
        - type: object
          properties:
            name:
              type: string
              description: bla bla bla...
              example: John Doe
        - type: object
          properties:
            admin:
              type: boolean
              description: bla bla bla...
              example: true

This definition should then somehow be referenced from the envelope description:

components:
  schemas:
    envelope:
      type: string
      maxLength: 1500
      description: |
        A JWT token. Please see [payload](#/payload)
      example: 'xxxxx.yyyyy.zzzzz'

The above example is not possible since internal-page links is not possible (to my knowledge) 😞