An evaluation of auto-generated REST API Documentation UIs

Here at Trustpilot everything is written following an “API first” strategy alongside a micro-service architecture. This works really great, and enables a multi language approach, where different teams can use different programming languages to achieve their goals, without having to worry (too much) about how it will affect future or legacy projects.

My team has been in the process of investigating options for a better documentation site for our REST API for both public and internal endpoints. We’ve investigated a lot of options that I’d like to share, and hopefully make the path through the jungle a bit easier for other people in the same situation.

“We have the language (Swagger & API Blueprint) to describe our APIs, lets begin providing more meaningful ways to engage with them as well.”
- API Evangelist

We‘ll focus mostly on Swagger

Our current documentation is actually built using a proprietary JSON format that was invented in-house before Swagger even existed. When Swagger gained traction, a decision to switch was made, to become more compatible with external tools and best practices.

Therefore this evaluation was mostly focused on projects that can build documentation from Swagger. Other standards exists, such as RAML, Apiary.io, ActiveDocs, Mashery I/O Docs, Mashape and more. We briefly looked at these but mainly to see if we would be missing out on fantastic features, and that didn’t seem like the case.

What we valued when evaluating

During the evaluation we weighed different things, some things were very important to us, others we could live without.

Automatic SDK generation

We really liked the idea, that we could offer custom SDKs for our API. We knew swagger-codegen could do this, so we didn’t value it that highly, since we knew we could always create a side project and do it there.

SEO Friendly

Some projects are 100% server-side and some are 100% client-side. Google is getting better and better at reading client-side code, but we still saw enough problems with getting pure client-side projects SEO optimized that we valued server-side solutions higher.

Themes and templates

We wanted to make the documentation site familiar and integrate it in our own look-and-feel. Some projects are not at all customizable, others allow you to reference a CSS file while others are fully customizable with templates and CSS.

Open source / activity

While not a limiting factor, sometimes it can even be preferred having a closed source company that provides support and development, we did look at the various licenses, some open source projects and forks were skipped from the evaluation because they didn’t have any activity for a long time.

Responsive

While not a 100% requirement, being able to browse the documentation from mobile devices were certainly looked at, and it came as a bit of a surprise that for example the de facto leader Swagger UI wasn’t responsive at all.

Try it now button

We really liked (and wanted) the “Try it now” button found in some API documentations, which will basically do a request in your browser for you, and display the result.

A walk-through of the different REST UI projects we looked at

After a rough first sorting, where we removed inactive projects, or projects that were obviously not suited due to very bad UX or the like, we ended up with a list of 10 possible candidates.

Postman (demo)

Automatic SDK generation
SEO Friendly
Themes / Templates
Open Source
Responsive
Try it now button

Postman is the de facto standard among developers for testing REST APIs, so it is an obvious strength that a lot of developers are already familiar with their tools. So when we saw they also had an option of displaying automatic generated documentation through their Postman Documenter we wanted to evaluate this as well.

Postman has a clean UI and nice code examples

A main feature is their “Run in Postman” button, which is a really nice thing, unfortunately this means that they don’t have a “Try this” button that doesn’t involve Postman. They do have semi-SDK generation though, with a lot of nice code examples.

A main drawback of Postman Documenter is that the documentation can’t be self hosted — it unfortunately has to be hosted on their cloud service. So while their pages are SEO friendly, you don’t have any influence on it at all.
Other than that, people who are not acquainted to Postman might be a bit confused, since the pages are somewhat heavily Postman branded.
Last but not least, then Postman Documenter is a paid solution, since it can’t be used outside of Postman cloud.


Swagger UI (demo)

Automatic SDK generation
SEO Friendly
Themes / Templates
Open Source
Responsive
Try it now button

Swagger UI was one of the first projects to automatically generate documentation based on Swagger. Released back in 2011, it is probably the UI generator with the largest amount of users.

Swagger UI has a “Try this” button, which makes it a breeze to test out APIs. Unfortunately the documentation UI generated looks a bit old, is not responsive and in my opinion basically tries to cram too much information into too little space.

The project is still active on Github and is merging lots of pull requests. Most of the effort seems non UI related though, so it’s unclear if they’re thinking about updating the look and feel to be more current.


Swagger-UI Responsive fork (demo)

Automatic SDK generation
SEO Friendly
Themes / Templates
Open Source
Responsive
Try it now button

A fork of Swagger UI that provides a much cleaner and simpler UI.

The project takes all of the good things of Swagger UI and improves upon them and adds lacking features. What’s added is things like responsiveness and a three-column-layout. It also comes with Swagger UI things like the “Try it now” functionality.

The project has slowed to a crawl on Github however, and while there does seem to be sporadic updates, the project seems mostly content to stay where it already is.


ReDoc (demo)

Automatic SDK generation
SEO Friendly
Themes / Templates
Open Source
Responsive
Try it now button

ReDoc is a project from apis.guru, and is basically an attempt to make a nicer Swagger UI, which design wise they quite succeed at. The interface is beautiful and simple to use. The project is quite new, so it’s lacking a bit of Swagger UI’s functionality, most noticeably the “Try it now” function. It does however have a nice and pretty support for code examples.

The project is very active on Github, but is being run mostly by apis.guru, which means their founder is having close to 99% of the activity on Github.


Rest United (demo)

Automatic SDK generation
SEO Friendly
Themes / Templates
Open Source
Responsive
Try it now button

Rest United is a paid service, which has a clear focus on their automatic SDK generation, which is definitely really good.

Rest United’s documentation site approach is heavily influenced by their SDKs and is therefore different than the other approaches we’ve seen. While still describing their parameters, requests and responses, the main focus of the endpoints naturally flow towards the SDK examples themselves. You can generate SDK’s for ActionScript, Android, cURL, C#, Java, JavaScript, Objective-C, PHP, Python, Ruby, Scala —with Javascript (Both web and Node) being mandatory.

The only option of styling the documentation is providing a URL to a .css file. There’s no “Try it now” button, but depending on your needs the SDKs and example code may or may not make up for that.

Rest United have awesome SDK’s and code examples

RAML / RAML2HTML (demo)

RAML’s interface is clean, and I love the grouping of endpoints

Automatic SDK generation
SEO Friendly
Themes / Templates
Open Source
Responsive
Try it now button

RAML is a competing format to Swagger, but there exists a swagger2raml project. While things might definitely get “lost in translation” by converting between the two formats, we’re keeping it in the evaluation mostly to show other alternatives exists.

The documentation itself is decent, and actually groups the various documentations by endpoints instead of having it split out on both endpoint and method — This is a lot simpler, and something I found myself wishing some of the other documentation tools would adopt.


Slate (demo)

Automatic SDK generation
SEO Friendly
Themes / Templates
Open Source
Responsive
Try it now button

Like Raml2Html, Slate is not Swagger. It does have a really nice interface though, so maybe it’s worth it for some to use a tool like swagger2slate for it.

The UI generally looks good, and the usability is great, but for some reason the author is really fond of the old Apple font embed graphical effect, which in 2016 just feels old.

There’s code examples, but as far as I could see, they’re not auto generated, so you’d have to supply those for yourself.

Slate has a nice 3 column interface

Readme.io (demo)

Automatic SDK generation
SEO Friendly
Themes / Templates
Open Source
Responsive
Try it now button

Readme.io is a paid service which provides a really user friendly way of writing your documentation site yourself and describing your API.

In general the design is pretty and usable and it’s easy to add pages and API endpoints. However it doesn’t currently support importing for Swagger, so everything has to be entered manually, which might not be a problem for small APIs, but for larger APIs it’s definitely a problem. I emailed them and they said Swagger import was coming AnyMomentNow™, so people who read this article might want to try it out.

Readme.io is simple, has a try it now button but no Swagger import :(

Custom built solution (screenshot)

Automatic SDK generation
SEO Friendly
Themes / Templates
Open Source
Responsive
Try it now button

We did a quick prototype to see how easy or challenging it would be to generate a custom UI on top of Swagger.

It was surprisingly easy, and we made headway fast. It’s basically just looping over a lot of JSON. But one thing is displaying the documentation itself, things like Automatic SDK generation and “Try it now” button will probably still be a challenge.

It also goes against the “Not invented here” principle while contributing to maintenance workload and we’d risk missing out on awesome new future developments that we hadn’t thought about right away.

Our prototype of a API documentation site

SDK Generation

While researching we found some options for SDK generation. We didn’t really get to test them all yet so I don’t want to talk a lot about them, but I thought I’d include them, since it’s very related:

In conclusion

We’re at a point where the automatic generation of API documentation has no clear leader. Some of the options we’ve seen seem to be after thoughts, programmed while solving another problem, and it seems like a project like Swagger UI could grab (or keep) most of the market by updating their look and feel to something really pretty and usable.

Currently though, there seems to be a business opportunity for some company to do this and combine it with Swagger-Codegen for automatic SDKs and make some kind of subscription service.


Written by Martin Mouritzen.

Like this post? Please feel free to comment and click “❤︎” to help spread the word, and don’t forget to click “Follow” for more.