Documentation is always the victim when developing a system. We will do it tomorrow. And tomorrow…

I’m writing this because we had a deep discussion about this subject in our team, and I would like to share what options we have checked and why we liked or disliked them.

Our aim is to build a documentation nice to read (e.g. Stripe’s doc) but also nice to write (and this is why we are here).

From our previous experience, tools that automate the conversion from the code (such as Swagger or Javadoc) are easy to write, but frequently written carelessly. They turn out to be neither easy to read nor useful for the final reader.

Our requirements are:

• We have several services, so we need an easy way to join all that documentation in our single site.
• That single site must look like a single piece of documentation, not a glued bunch of several documents.
• Easy to navigate and consume: we want to use it as an introduction to the APIs for the newcomers.

Third-Parties systems

At the beginning, we tried to use existing solutions.

Main advantage: you don’t have to invest your own time building the system. Major drawback: your documentation is locked in that system. Not very customizable.

Postman API / Collections:

Adding requests to collections is easy. Writing details in them is not so easy. Besides, it is a bit dark what part of the documentation you have to change after making changes to the service if you are not an expert on that service.

Postman API can be written in OpenApi format but there is no HTML view for them.

Static documentation for collections is nice and readable, but there is not a main documentation that acts as entry-point for the documentation.

No useful version control. Documentation locked in Postman.

Apiary:

It uses API Blueprint format, which is nice to write. From our experience, it’s a hell to maintain (no version control, what happens with multiple people editing the single document).

A bit pricey. Documentation locked in Apiary.

In-house / custom systems

So that, we gave up trying to use someone else’s system.

Slate (plain):

Generates static sites from markdown. Simple, a bit ugly by default, but quite tuneable. We can deploy the static site in Github pages (free!).

Main drawback: writing schemas in tables are a bit unreadable, because the description of some fields may be a bit long. And I don’t want to write tables/html, I want to write documentation.

Slate + Custom tunning (e.g. Monzo’s):

Prettier but it will be difficult to merge changes from the original Slate repo (although I’m not sure whether there will be changes often).

Main drawback: it is nicer but I feel they are “cheating” in the markdown, as they are including html tags to make it prettier.

For example, request/response parameters are tables of two columns, but the required keyword is in a span tag written in the first column of the markdown. That’s a bit trickier to write. If we don’t like that format in the future, we have to change all markdown files.

Slate + OpenApi converter:

What we liked about OpenApi is that it is a standard format and we didn’t have to care how it is displayed. On the contrary, we didn’t have a nice way to convert from openapi files to a static site.

Given that, our approach has been to write schemas and endpoints in OpenApi format (we already had a lot of this work done in Postman APIs), automatically transform them to markdown, then use slate to generate the documentation.

OpenApi-Generator and Widdershins allow us to use templates to transform the .yml into .md. You can choose to transform schemas into tables (like Monzo) or nested div (like Stripe). If you dislike that format in the future, we only have to change that template and rebuild the project.

Service description will be written in plain markdown.

For example, payments documentation might consist on two files:

• payments-section.md: Manually written introduction to payments, their lifecycles, details or highlights, …
• payments-api.yml: OpenAPI file describing schema and endpoints.

In order to automate the building of this site, every *-api.yml is transformed into a *-api.md after pushing. Then Slate site is built.

Pros:

• Easy to write (markdown for descriptive text, openapi for schemas and requests).
• Easy to change (templates to transform openapi to markdown, css and layout.rb to change Slate)
• Easy to deploy (widdershins + slate + github page)

Cons:

• Maybe too many steps that can fail (widdershins + slate)

Conclusions:

No free lunch. You have to spend your own time building your documentation site if you want happy API consumers and happy developers writting it.

You can check a simplified version of Playtomic’s solution at (https://github.com/sgmoratilla/openapi-slate-doc-example).