Uploaded image for project: 'camunda BPM'
  1. camunda BPM
  2. CAM-13465

Make Swagger UI easier to navigate

XMLWordPrintable

    • Icon: Task Task
    • Resolution: Won't Fix
    • Icon: L3 - Default L3 - Default
    • None
    • None
    • run
    • None

      Motivation:

      After completing the OpenAPI spec, the list of resources and endpoints in Swagger UI has become very long. If, for example, you open a Get List endpoint, but you would rather use the Count endpoint instead, you need to: either scroll back to the top of that get list endpoint to close it or scroll through it to get to the Count endpoint. 
      Both might involve quite a lot of scrolling as these endpoints can be quite long. 

      Additionally, this makes it hard to keep track of where you are and what other methods and endpoints might be available to you. (See gif) In my experience this somewhat reduces the attractiveness of using swaggerui. 

      Acceptance Criteria:

      The user can see at on glance: 

      1. Which resource they are currently looking
      2. They can switch most another endpoint/method without scrolling after opening an endpoint/method

      Hints:

      In my opinion there are 3.5 ways to achieve this.

      1. As the swagger-ui maintainers to implement a better layout. (unlikely to result in any quick changes)
      2. Hook into the swagger-ui layout ourselves via React (https://github.com/swagger-api/swagger-ui/blob/master/docs/customization/custom-layout.md). However, I do not know how powerful that mechanism is. (See mockup)
      3. Use another rendering library for openapi. ReDoc seems to be one of the better ones. Unfortunately, it does not offer the try-out-now functionality of Swagger UI. That is part of their commercial offering, apparently. 
      4. Reduce the default font size. (That at least makes it a bit easier to keep an overview) 

       

       

        This is the controller panel for Smart Panels app

          1. mockup.png
            342 kB
            Anton von Weltzien
          2. swaggerui-scrolling.gif
            26.04 MB
            Anton von Weltzien

              Unassigned Unassigned
              anton.weltzien Anton von Weltzien
              Votes:
              0 Vote for this issue
              Watchers:
              3 Start watching this issue

                Created:
                Updated:
                Resolved: