Swagger UI vs. Redoc

[fyliu]

I was listening to a talk from the Write The Docs conference on API documentation. Now I can see the speaker's right about redoc's page display being superior to swagger's.

Swagger's interface is made for small screens and wastes space when using a normal screen where developers usually write code.

Terminology

• OpenAPI (specification for APIs, formerly synonymous with Swagger)
• Swagger UI(the dominant major web interface display tool for OpenAPI)
• ReDoc (another web interface display tool for OpenAPI, made by ReDocly)
• Another link about Swagger vs. OpenAPI.

Demo site

• ReDoc UI
• Swagger UI

Slides

• google drive folder
• slide deck

[fyliu]

Here's Redoc's display of the User endpoints and the first one listing the users, plus sample data. Notice these things:

1. I can see many models at a glance on the left and expand their endpoints
2. The endpoint description is in the middle with bulleted parameter names and types, plus descriptions and examples if included, plus any input limitations like <=255 characters

[fyliu]

Here's the Swagger UI.

• It might as well be on mobile
• The endpoint names are more visible than what they do, which is not necessary, since they're all /user/...
• I have to do a lot of scrolling to get to other endpoints
• There's no quick list of all the models
• You have to click on the endpoint to view the details, then click on another one to see their details.

[fyliu]

At 30% zoom, I was able to fit this endpoint into a single screen 1080 pixels high, so 3 screens at 100%. Imagine a developer scrolling through to figure out what needs to go into the request. Imaging that developer looking up a handful of endpoints!

[fyliu]

Here's a 100% screen of some fields.

• most of the info is justified left, making it hard to glance at the field names
• it does distinguish between (query) and (path) parameters in the list. However, redoc just puts them in a section called "QUERY PARAMETERS"
  

[fyliu]

Here's a comparison of the request body parameters.

1. redoc shows in an easy to read list

   • field name (first_name)
   • type (string)
   • input limit (<= 255 characters)

   

2. swagger shows just the field names (first_name), but require clicking on each one to show the type (string) and input limit (maxLength: 255)

   Imagine an developer having to figure out just a handful of endpoints, clicking through all the fields!

   

[fyliu]

WIP Quick summary

Swagger UI

• con - requires lots of scrolling (all information displayed vertically)
• pro - good for mobile (all information displayed vertically)
• con - not good for desktop (all information displayed vertically)
• con - requires clicking on each field (data field types not displayed by default)
• con - inconsistent structuring (some fields have types underneath and some have types on the right)
• con -

ReDoc UI

• pro - less scrolling (information in 3 columns)
• pro - makes better use of horizontal screen space (information in 3 columns)
• pro - viewable on mobile
• pro - useful desktop layout hierarchy (models and endpoint on left column, endpoint descriptions in center, example on right)
• pro - readable parameter field display (name, type, limits)