how to navigate a large OpenAPI schema with enums and formats

Question

I have a large OpenApi schema I need view & understand. Perhaps I'm just missing something but neither Postman or SwaggerUI make this easy. classes ("type":"object"s) are handled OK - but other critical elements do not have their details displayed:

• formats do not display
  • {"type":"string", "format":"uuid"} --> just displays as {"type":"string"}
• enums don't display their values, or even that it is an enum 'type'.

By "large" I mean a few thousand lines of yaml in the spec, a couple hundred types, etc. Sure, one can navigate the yaml directly ... but this completely negates the purpose of the graphical interface, and is incredibly slow for a large document.

here's a screenshot from SwaggerUI. I would expect the AnEnum schema to show that it's an enum, and it's values; and AClass.single_nested.a_list is a list of uuids ... with only string it's not helpful. Postman isn't any better; it generates example data, which does fill in uuids with a valid UUID; but values for enums are just ~lorem ipsum (ie actually invalid, despite Postman having access to the enum values)

Don't love the wall of text, but here's the yaml that generated this.

components:
  schemas:
    AnEum:
      description: An enumeration.

              ###############
      enum:   ############### <- nothing useful is shown for enums
      - foo
      - bar
      title: AnEum
    AnotherClass:
      properties:
        a_list:
          items:
            type: string
            format: uuid
          title: A List
          type: array
      required:
      - a_list
      title: AnotherClass
      type: object
    AClass:
      properties:
        single_nested:
          $ref: '#/components/schemas/AnotherClass'
        an_enum:
          $ref: '#/components/schemas/AnEum'
        ## lots and lots
      required:
      - an_enum
      - single_nested
      title: AClass
      type: object
  securitySchemes:
    BearerTokenAuth:
      bearerFormat: JWT
      scheme: bearer
      type: http
info:
  description: 'dump a quick example'
  title: demo full schema 2
  version: 0.0.1
openapi: 3.0.2
paths:
  /api/v12345/somepath/{id_in_path}/:
    get:
      description: '...'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AClass'
          description: success
          ## lots and lots
      security:
      - BearerTokenAuth: []
      summary: none
    parameters:
    - description: the id_in_path as a UUID.
      in: path
      name: id_in_path
      required: true
      schema:

                        #########
        format: uuid    #########  <---  format not shown graphically
        type: string

Any graphical tool that displays the "full" schema graphically would be fine; the primary necessary feature is the same as why an IDE has 'go-to-definintion'. SwaggerUI's "expandable" formatted tree works, too (if it had the information)

Answer 1

In Swagger UI schema view, the format is displayed in parentheses after the type name. For example, type: string + format: uuid is displayed as string($uuid).

Enum values not being displayed is a bug that only affects enums without an explicit type. This bug will be fixed in the next release of Swagger UI/Editor. The workaround is to add the type to the enum:

    AnEum:
      type: string   # <------------
      description: An enumeration.
      enum:
      - foo
      - bar
      title: AnEum