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.
Best combination that we found:
- Use OpenAPI 3.0
- Implement specification with VSCode Swagger Extension
- Use GitHub pages with Redoc for a good looking & free hosting
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:
- API Blueprint
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.
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:
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 :)
I then looked into Swagger editor (https://editor.swagger.io/) but I opted for a self-hosted via Docker:
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:
With the extension you get:
- 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:
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.
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:
Put your openapi.yaml or swagger.yaml in a publicly accessible place. In our case I have put it in a Git repo:
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.
In your website add these lines:
<script src="https://cdn.jsdelivr.net/npm/redoc@next/bundles/redoc.standalone.js"> </script>
And that’s it, your API reference is now hosted:
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/