I’ve been looking for a solution for REST API documentation for a long time. This weekend, after hours of struggling with swagger, here are the things I experienced.

Before using swagger, there is already some documentation I wrote in Markdown. The first step would naturally be translating these plain text to swagger’s language, OpenAPI specification. I spent about six hours translating these documentations, including the time I learnt OAS. The process of using swagger is similar to using a static site generator.

The experience of writing an OAS specification is tedious. This language is definitely not designed for easy writing. To express a concept I had to read a lot of OAS’s documentation and write tens of lines of YAML. The major part of the YAML is about how a concept is implemented in OAS instead of what the author wants to express. Even with $ref, one could reduce some copy-paste, the lack of abstraction of YAML soon led to the chaos of the whole file. 14 API endpoints were translated to 768 lines YAML with deep indents. I would consider the work I’ve done as writing assemble language.

What about using an OAS specification? One needs to use swagger UI, a tool to render an OAS specification to a web page so anyone who will consume the API can easily read the documentation. I found the UX design of swagger UI is bad, which made me had to scroll a lot and click a lot to get what I want.

I also tried an alternative to swagger UI called Redoc. It has excellent UX, usually, any navigation only involves a few clicks, and I don’t need to scroll a lot to find the right documentation. A critical disadvantage of Redoc is the way it arranges information. I always found I get lost in the simple page generated by Redoc. especially when I scrolled the page for a few.

In the end, I had to give up. The conclusion I got is that OAS is suitable for a single set of REST API designed to be consumed for many developers outside the corporation who host the API. Otherwise, the complication of OAS and the lack of abstraction of its YAML syntax won’t pay off.

So what is a good API documentation solution? Given the complex nature of HTTP and numerous nonstandard ways of using it. It is hard to define a single tool to suit everyone’s needs and make everyone happy. There has to be a trade-off between generality and usability. The top priorities I would consider when designing such a tool is as follows.

First, it has to be developer-friendly. Using YAML like OAS makes API documentation hard to write. A better approach is not a configuration language like YAML but an more expressive language.

Second, it has to be single-purpose oriented. Trying to combine API validation, API testing and API documentation in a single tool led to the complexity of the OAS standard.

It seems such a tool hasn’t existed yet. I guess the essential difficulty of API documentation is not technical.