Webhook Relay

Documenting your API with OpenAPI (Swagger) and Redoc

Karolis Rusenas
By Karolis Rusenas · Nov 5, 2018

In this article, we will review several popular editors suitable for documenting APIs with the OpenAPI 3.0 specification, different themes that can render the spec, as well as hosting strategies.

TL;DR

Best combination that we found:

Choosing API specification format

I guess it’s safe to say that OpenAPI is now the most popular API specification out there. You can find out more about it here: https://www.openapis.org/. Other contenders:

  • RAML
  • API Blueprint
  • WADL
  • Slate

You can read more about other top specification formats on an excellent Nordic APIs article here: https://nordicapis.com/top-specification-formats-for-rest-apis/

OpenAPI vs/and Swagger

Short history: OpenAPI 3.0 was the first official release since it was donated to the OpenAPI initiate by the SmartBear Software (and renamed from the Swagger Specification). A lot of people still think (myself included before I did some research) that Swagger is still a specification, however, currently:

  • OpenAPI is a specification

  • Swagger provides tools for writing specification, generating code & hosting it.

In the past years, OpenAPI has been embraced by major enterprises and startups of various sizes.

Editors

Once you have a specification chosen, it’s important to look for a good way to actually write it down. I initially started with https://apiary.io as they offer an editor with Swagger 2.0 and API Blueprint options (defaults to API Blueprint so watch out:) as well as hosting your documentation on their service:

Apiary editor

Sounds like a good deal? It probably is, since it offers an all-in-one package - editor, syntax check and even hosts your docs for free. Let’s have a look at other options :)

Swagger editor

I then looked into Swagger editor (https://editor.swagger.io/) but I opted for a self-hosted via Docker:

Swagger editor

It’s very similar to apiary.io offering but the main problem I found with both of them was that they are just not as fast as my editor that I use locally.

Swagger VSCode extension

Naturally, I checked out VSCode extensions marketplace and found this excellent piece https://github.com/arjun-g/vs-swagger-viewer:

Swagger editor VSCode

With the extension you get:

  • autocompletion
  • all your shortcuts work
  • integrated Git

All in all, while I started documenting API in Apiary, by switching to VSCode extension it greatly improved the speed at which I could document.

Hosting your documentation

While I really enjoy both Swagger 2.0 and OpenAPI specification format, swagger docs weren’t particularly visually attractive to me. Apiary does offer a nice theme:

Apiary docs

And would probably be my first choice of hosting if we didn’t already have a website where we host docs. But at the end of the day, it’s just a single page and having a 3rd party hosting dependency was a bit too much.

Enter ReDoc

After spending a bit of time looking at various themes and tools, I found my favorite - ReDoc (https://github.com/Rebilly/ReDoc.) It offers an incredibly nice theme, the project is active and very customizable. The main reason I chose ReDoc was because of how easy it is to embed documentation with it:

  1. Put your openapi.yaml or swagger.yaml in a publicly accessible place. In our case I have put it in a Git repo:
    https://github.com/webhookrelay/swagger-webhookrelay/blob/master/openapi.yaml
    Storing it in a git repo offers a nice feature - you edit, push it and it always stays up-to-date without redeploying your website.

  2. In your website add these lines: 

<script src="https://cdn.jsdelivr.net/npm/redoc@next/bundles/redoc.standalone.js"> </script>
<script>
   Redoc.init('https://raw.githubusercontent.com/webhookrelay/swagger-webhookrelay/master/openapi.yaml', {
       scrollYOffset: 60,
       hideDownloadButton: true
   }, document.getElementById('redoc'))
</script>

And that’s it, your API reference is now hosted:

Redoc Webhook Relay API reference

Conclusion

Documenting your API can be quite fun if you pick the right tools that are not slowing you down. In our case we used a nice editor with features tailored to OpenAPI spec and publishing your API docs to the world can also be a pain-free experience.

Obviously, suggested tools were only the best for me, I suggest that before you start documenting your own APIs you would also do a 30-minute research with some trials on different editors, themes and hosting. Maybe you will find some other combination that suits you better. At the end of the day, choosing the right tooling will save you a lot of time :) good luck! Worst case scenario - once the specification is done, it’s easy to try out different themes and hosting options as well.

Bonus: Swagger 2.0 to OpenAPI 3.0 converter: https://openapi-converter.herokuapp.com/

Reference