Finding the Best Tool for REST API Documentation
Recently I’ve been doing a lot of research about the documentation tools for REST API, and I found that there are tons of such tools out there. With that, a natural question that came to my mind was: “Which tool is the best?”. You will probably ask the same question if you need to deliver documentation for your REST API.
It sounds to be a simple question, but difficult to answer, because many other questions need to be answered before we can come to a meaningful conclusion.
In this article, let me guide you through these questions and see if I can help you find your ideal documentation tool.
- Who are your API users?
Your API users might be developers in your organization, outside your organization, or both. Understanding their needs is your top priority because they are your customers and ‘customers are always right’.
If necessary, you may want to further categorize these users. For example, internal users might be your front-end development team or your delivery team that helps customers implement their solutions. If the APIs are developed by your back-end team and consumed by your front-end team, you won’t need anything fancy, because those teams usually work closely together and API users won’t care too much about formal documentation because they have access to your design documents or even the API specification file itself. On the other hand, your delivery team may have higher requirements as they may not work that closely with your development teams. The expectation from external customers may be even higher because they can only rely on your API documentation to do their job. In addition, the more they use your API, the more they help you promote your business.
The answer to this question can provide useful input for other questions that follow.
2. How do you want to publish your API documentation?
Based on the needs of your target users, you can decide how and where to publish your API documentation.
If the APIs are only consumed locally within the organization, and you do not want to expose them to outsiders, you may choose to host the documents on an internal server, such as locally hosted Swagger UI or a web server. If you want to host the documents on a third-party platform, such as Stoplight, you will need to use user accounts to protect your content.
API documentation is mostly published in the HTML format. However, if your users prefer to read PDF documents, you will have to consider that and find a tool that can generate content in that format, for example, Swagger2pdf or RapiPDF.
3. How do you want to integrate your product documentation with your API reference documentation?
In general, APIs do not work alone. They usually provide an optional way of using various features of your product. To make good use of the APIs, developers must first know what features are available and the intended usage of each feature. That is the reason why they need to read not only the API reference documents, but also the product documents that provide conceptual information about product features.
If the product documents and the API reference documents are distributed separately, for example, product documents embedded in the product as web help and API documents hosted on your company web site, you will have the freedom to choose different authoring tools for them.
If you want to closely integrate these two types of documents and even present them as one single document, you will either need to find tools that can work together or find a tool that can handle both types. For example, some professional technical writing tools, such as Paligo, can import OpenAPI specification files and generate relevant API reference topics, which can be handled as any other topics in the document.
4. Who will be writing your API documentation?
Product documentation is usually handled by a technical writing team. However, API documentation might be different, as the content is relatively more technical. Some organizations use technical writers, while others use developers.
Developers and technical writers usually have different skill sets and therefore they prefer different tools. Developers may want to use markdown whereas writers may prefer DITA. Based on that, you will need to choose a documentation tool that can accommodate their preferences.
5. What is the API toolchain used in your organization?
Many API tools are actually toolchains that accommodate API design, editing, documentation, publishing, etc., which means if the toolchain already comes with a documentation tool, you may not have to find another one, unless the included tool cannot satisfy your needs.
There are a lot of benefits in using a toolchain. For example, writers and developers can efficiently collaborate on the same platform. In addition, if documents are automatically generated from the specification file, their contents are always kept up to date. Whenever the specification is changed, relevant changes are reflected in the API documentation instantly.
6. How do you want your API reference information presented?
One role model of API documentation is the stripe API documentation. Its three column format is considered by many people as the industry standard. However, its API documentation tool is developed in-house. Nevertheless, now many tools, such as Redoc, can be used to generate three-column API documentation.
Although the three column format is popular, it may not be the best. For example, the code samples might be difficult to read if the line is too long. Luckily, there are also tools available that can generate two-column or one-column API documentation.
Another aspect you need to consider about content presentation is if you need the page to be responsive, suppose the HTML format is used. Along with the increasing popularity of mobile devices, it is important that your documents are well-presented on different devices with different screen resolutions.
7. Are you planning any infrastructure changes in the long term?
If you choose to use a third-party platform, you may fall into the trap of “vendor lock-in” because you may use some proprietary features provided by the tool or platform. For example, you can use the x-codeSamples field to add code samples for Redoc, but once you change to another platform, will those samples still be supported?
So if you envision some future infrastructure changes, think about the direction you are going and consider that when you select the API documentation tool. You don’t want to do a lot of rework when you migrate to a new system.
8. Do you want your API documents to be interactive?
For some developers, the capability to try out the endpoints is quite important, because they need to try an API before starting to formally use it, and trying the API while reading the documentation is a very convenient way to achieve that.
For that reason, many API documentation tools provide the “try it out” feature, and among such tools, Swagger might be the most popular one. If you need such interactivity, you will need to find a tool that provides such features.
Anyway, further considerations beyond API documentation are needed here. You don’t want all your records to be removed from the database and neither do you want developers to insert records continuously until your system is out of resources.
These are just some key questions that you need to ask yourself before deciding what tool to use for your API documentation. The list can grow to be very long. For example, are you cost sensitive? Some tools charge expensive monthly license fees, some tools charge one-off license fees, while some other tools are open source and completely free.
Before determining an API documentation tool, ask yourself all these questions and make a list of all relevant requirements. Then look at all the available tools. The tool that can tick most of the boxes is the best tool for your API documentation. There is no “best” tool in the world. The tool that can satisfy most of your requirements is the best tool for you.
Hope that you are inspired at this point. Regarding the API documentation tool, you can even think outside the box and develop your own tool, if you have people who are technical enough. OpenAPI is a public standard, and many languages can be used to parse OpenAPI specification files. For instance, Tom Johnson gives a good example of using Liquid in Jekyll to parse a specification file. If you can do that, you can easily generate API documents in whatever format you want, without the restriction of any ready-made API documentation tools.
