by Alexander Yu
In software engineering, dev teams often dismiss documentation as tangential—secondary to product development and feature work. While code design and implementation is a top priority for most software engineers, creating good documentation should carry equal weight in the product development process.
In a nutshell, documentation is like a manual for your software: it tells users how to use your API. But in addition to the “how to,” great API documentation also helps users derive maximum value from your software, ensuring they don’t miss important features or waste time misusing your API. So having good API documentation is crucial in helping your product establish a strong user base and retain users in the long term.
However, keeping your API documentation up-to-date can be difficult and tedious, especially if you have to manually edit it every time your API changes. Luckily, there’s a wealth of API documentation tools out there to help simplify and automate doc generation.
This article will focus on a handful of the most popular ones: SwaggerUI, ReDoc, ReadMe, apiDoc, Postman, and Bump.sh. In our discussion of each tool, you’ll consider factors such as features, ease of usage, current community support, and pricing to help you determine which one is best for your use case. If your end goal is to create and maintain excellent API documentation without too much hassle, read on to learn more about these tools.
Swagger UI
Swagger is a set of open source tools that help you design and build an API, which you define using an OpenAPI Specification (OAS). In particular, Swagger UI is a tool that takes your OAS and automatically generates documentation for your API in an interactive HTML page.
Above is an example of what Swagger UI can generate based on an OAS. This API models a pet store where users might expect to be able to do operations like add a pet to the store and retrieve details of a particular pet.
Here, a POST method for uploading an image of a pet is expanded. Swagger UI includes all the documentation details required to use the API: endpoints, available operations, parameters, responses, data types, descriptions, and even examples. Also, notice how easily users can test the API by clicking the Try it out button.
Because so many APIs are already built using the Swagger framework, it takes little to no effort to automate API documentation using Swagger UI. This makes it an ideal use case for APIs that you build using an OAS.
Why Choose Swagger UI?
- Features: Provided you have an OAS, Swagger UI automatically generates a full HTML visualization of your API, complete with API documentation and built-in testing.
- Ease of use: Swagger UI is suitable for developers of all skill levels. Everything generated by Swagger UI is taken from an OAS file, and there’s no additional setup required beyond that. When your OAS changes, your Swagger UI documentation changes as well to automatically reflect your new API.
- Community support: Swagger is open source and is one of the most popular tools for creating RESTful APIs. Because of this, Swagger UI has a huge user base, making it easy to get actively involved with the community.
- Pricing: You can access all Swagger UI features for free. For development teams that want a hosted version, Swagger’s cloud version, called Swagger Hub starts at $75/month. Swagger Hub’s paid plans also include more integrations like GitLab, Bitbucket, and Azure DevOps.
- Limitations: Swagger UI doesn’t offer the best developer experience and is not SEO-friendly, if you need your documentation publicly published.
ReDoc
ReDoc is a tool that’s similar to Swagger UI. It also takes an OAS and renders an interactive HTML page with full API documentation details; however, it has a notable difference.
In the above screenshot, we’re looking at the same Swagger-based pet store API, specifically the same /pet/{petId}/uploadImage POST method as before. However, compared to Swagger UI, ReDoc arranges the page in a modern three-column format, where the left column is for navigation, the central panel contains documentation, and the right panel contains examples.
The three-column format is perhaps the most popular API documentation format today, used by many well-known companies like Twilio and Stripe. The three-column format allows developers to view API documentation in tandem with related code samples.
Why Choose ReDoc?
- Features: ReDoc automatically generates interactive API documentation based on your OAS. It’s very similar to Swagger UI, but the main difference is that ReDoc renders the documentation in a modern three-column format.
- Ease of use: Like Swagger UI, ReDoc is very easy to use if you already have an OAS. Whenever you make updates to your API, ReDoc re-renders automatically, so there’s no need to make manual edits to your documentation.
- Community support: ReDoc is an open source tool with a large customer base, along with extensive documentation and tutorials to help you answer questions.
- Pricing: ReDoc is Redocly’s community-edition product that’s free to use. You can get more features on paid plans, for example, Redocly’s Basic tier ($69/month) lets you create public documentation and add multiple users, while the Professional tier ($300/month) allows you to remove their branding and get an integrated developer portal.
- Limitations: The documentation drift problem exists for ReDoc, and it’s not as easy to customize as some options on this list. That said, their vendor extensions allow for much more customization than in SwaggerUI does.
ReadMe
ReadMe is a tool that offers a little more in terms of customization compared to Swagger UI and ReDoc. By default, it also generates a hub that contains all your API documentation in a three-column layout.
The above is taken directly from ReadMe’s documentation. You can clearly see the details of a particular GET API, along with code samples and a Try it! button in the right column for testing.
ReadMe supports reading an OAS out-of-the-box for quick adoption. But what makes ReadMe stand out is that it allows for more customization in developing your documentation hub. In particular, you can add custom guides and tutorials, which is great if your APIs are designed to be used together. In addition, ReadMe has built-in monitoring features that allow you to track usage metrics for your APIs.
Why Choose ReadMe?
- Features: ReadMe generates an API documentation hub based on an OAS or via a manual API editor. It also supports various customization features and ways to monitor your APIs.
- Ease of use: Since ReadMe has the option of uploading an OAS, it’s still very easy to get started with. However, it also caters to more advanced users or those looking to write custom guides and tutorials in addition to the base API reference.
- Community support: ReadMe has a wide customer base, including companies like Clover and UiPath. There are also discussion forums that you can use to pose questions to the community.
- Pricing: ReadMe’s Free tier is good for getting started with your API reference and metrics. To customize your guide, you’ll need to upgrade to at least the Startup tier ($99/month) or above.
- Limitations: ReadMe’s new editor doesn’t allow for as many formatting options as some other tools, and while you can write guides and tutorials in the platform, it doesn’t allow you to upload project files to the portal.
apiDoc
Compared to the first three tools, apiDoc takes a different approach towards generating documentation. Rather than rely on an API definition file like OAS, apiDoc is a package that allows you to add documentation directly into your source code through annotations. While there are third-party libraries that can create OAS files based on code annotations, having this built-in makes apiDoc slightly better if you want to control documentation through code instead of having a separate tool.
The screenshot above shows a typical apiDoc page (here’s the live demo) displaying details for a POST method. Content on this page is generated according to annotations in your source code: for example, the list of query parameters are generated through @apiParam tags in your code. This allows you to keep your internal documentation (geared towards developers working on the codebase) and external documentation (geared towards your users) in sync.
Why Choose apiDoc?
- Features: apiDoc generates documentation based on content that you include in apiDoc annotations directly in your source code.
- Ease of use: Setting up apiDoc is easy, but it does require you to become somewhat familiar with apiDoc’s capabilities before you can use it to its maximum potential. In addition, updating the documentation may require a deployment since your docs are embedded with your source code.
- Community support: apiDoc has a relatively smaller user base, but it’s still used by over eleven thousand developers according to GitHub.
- Pricing: apiDoc is absolutely free to use!
- Limitations: Because apiDoc doesn’t follow a community-led API specification, it’s harder to migrate to and from it. This also adds to the learning curve as you’ll have to make sure you know their rules for annotations.
Postman
Postman is an API platform for designing and building APIs. Postman’s API Documentation Tool helps you generate, edit, and publish your docs. Since Postman has one of the largest developer communities out there, it makes sense to choose Postman’s API Documentation Tool if you’re already integrated within their ecosystem.
The screenshot displays generated documentation in the three-column format. Postman can automatically generate basic documentation based on your API’s schema (i.e., an OAS file), but you can also add custom documentation in certain areas. For example, under Get a list of items, there’s custom documentation to describe the operation in more detail. In the top right corner, Run in Postman also allows you to test out APIs directly from the documentation page.
Why Choose Postman?
- Features: Postman generates documentation based on an API schema definition while also allowing you to customize and edit documentation before publishing.
- Ease of use: Like most tools on this list, Postman can take an existing OAS file and generate documentation. It can also be used as a standalone app, or directly in the browser.
- Community support: As a platform, Postman is perhaps the most popular for building APIs (more so than Swagger). This means it has one of the largest developer communities in the software development world.
- Pricing: For up to three users, Postman’s Free tier will do. For more integrations and capabilities, Postman’s paid tiers are usually more cost-efficient than some of the other tools, with its Basic tier priced at just $12/user per month.
- Limitations: Postman is a very powerful tool with many features, but this can make it overwhelming for users who are new to the tool or who only need to create simple API documentation.
Bump.sh
Bump.sh is a tool that’s swiftly gaining popularity as it combines many of the best features from the previous five entries in this roundup.
To start off, you have OAS support: Bump.sh can take your existing OAS and instantly generate documentation for you.
Next, documentation is generated in a three-column layout, which offers an ideal viewing experience. In addition, Bump.sh supports AsyncAPI specifications as well, so it allows you to automate documentation for event-driven applications in addition to REST APIs.
Finally, Bump.sh’s webhooks can be used to notify other tools and services each time you make a change to your API. For example, you could broadcast changes to a Slack channel or send email alerts to consumers. This helps you ensure that teams are notified when you make structural changes to your API.
Why Choose Bump.sh?
- Features: Bump.sh can generate documentation not only from RESTful API specs like OAS but also from event-driven API specs like AsyncAPI. It also allows for custom documentation, automatically creates a changelog for you, and allows you to segment your API documentation into “hubs” for better organization.
- Ease of use: You can set up Bump.sh in just a few minutes and quickly start generating documentation. Any OAS or AsyncAPI spec can be used as a starting point, making it a very easy tool to use.
- Community support: Bump.sh is a new tool but has a growing developer community and customer base.
- Pricing: Bump.sh is free to get started with. As you start to scale up, you’ll need the Startup tier ($149/month) or Business tier ($599/per-month), although open-source projects can get access to all Business tier features for free upon request.
- Limitations: Bump.sh doesn’t have an API Explorer yet, but you can use a Postman collection in the meantime. Like many tools like Postman or Readme, Bump.sh is not fully open-source.
Conclusion
API documentation is a task that developers should never overlook. Instead of manually updating documentation each time the API changes, many companies now use tools to automate doc generation.
In this article, you got a roundup of six of these tools, all with their unique features and capabilities. You could opt for a more minimal tool like Swagger UI or one that allows for more customization in both content and presentation, such as ReadMe. Of course, ease of use, community support, and pricing are important considerations to make too.
Bump.sh is the best way to automatically create API portals for internal and external users. It’s also the only tool on our list that explicitly supports all OpenAPI specs (Swagger, v3.0, v3.1) or an asynchronous API definition like AsyncAPI, which is important for modern event-driven architecture (EDA). Feel free to look at our solution, and please reach out if you have any feedback, comments, or suggestions you’d like to share. We’re always listening.
