Forum Discussion

HenrikHL's avatar
HenrikHL
Frequent Contributor
3 years ago

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

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's avatar
    frankkilcommins
    Staff
    3 years ago

    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's avatar
    HenrikHL
    Frequent Contributor
    3 years ago

    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) 😞