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

  • 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

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