Which API documentation tools?

In the previous posts, we covered API gateway platforms and API testing frameworks.

This post covers the popular API documentation platforms, tools and frameworks.

Documenting APIs

Managing APIs you own as products requires to understand the business value your APIs provide and enables long term operating view.

Every valuable technology product aims to provide its customers with helpful documentation and usage guides.

We created a list of popular API documentation tools and frameworks which can help you build great API product experience.

API specification frameworks

OpenAPI Specification. It's a community driven project - part of Linux foundation. The aim for this specification is to provide the programming language agnostic Rest API interface definition.
Swagger Specification. Is a predecessor of OpenAPI spec. In 2015 several large technology companies joined the Swagger specification initiative and it was renamed to the OpenAPI. Swagger kept its name and became a set of tools designed for the implementation of OpenAPI spec.
RAML is described as Restful API modelling language and specification. Similar to OpenAPI it is machine readable and human reader friendly.
API Blueprint. It's simple, yet powerful Rest API description language and specification. It encourages module reuse and provides support for data description syntax.
Async API specification aims to be industry standard for defining asynchronous APIs. Mostly used to provide specifications in event driven architecture enviroenments.
I/O Docs Definition. It's an API specification format used by Tibco enterprise product range. Not being actively maintained. Nevertheless, you might still come across it within many legacy enterprise technology stacks.

API documentation tools

Swagger tools. After renaming Swagger specification as OpenAPI, Swagger concentrated on becoming popular toolset for working with OpenAPI. Most popular tools: Swagger Editor, Swagger UI and Swagger Codegen.
Optic. OpenAPI linting, comparing and testing utility. Optic can detect changes between two versions of an OpenAPI specification using Git tags or branch names.
Treblle. API platform offering API documentation, API observability, analytics, security monitoring and governance. Its a commercial offering, with free tier available for trying it out. Supports multiple programming languages and custom integrations.
OpenAPI tools. Is a solid collection of tools and frameworks to work with OpenAPI specification. Including schema validators, data validators etc.
API Blueprint tools. For those who are using API Blueprint specification in their their API lifecycle. This is official list of API blueprint specification tools, including parsers, renderers, mock servers and others.
RAML tools. This code repository contains multiple tools. Parsers for most popular programming languages (Java, JavaScript, Python, .NET etc.), mock examples and others.

API documentation libraries

Springfox. Library for Java / Spring framework to auto generate Swagger UI page directly from the microservice which provides the Rest API implementation.
Swagger-jsdocs. Library for JavaScript / NodeJS to automate OpenAPI documentation generation.
Fastapi. Is a Python framework for building microservices. It includes the setup for autogeneration of OpenAPI based documentation to document Api functionality. Implements Swagger UI and ReDoc.
Pact. Framework supporting multiple programming languages (JVM family, JavaScript, Ruby, Go, .NET). Enforces consumer driven specification for Apis. Provides machine readable documentation formats.

API standardization

OpenBanking. Is a prescriptive API specification accessing financial data and financial services. Licensed under MIT open source license.

Summary

Remember that good quality API product documentation requires time and effort, but it can be the factor which significantly increases your API product adoption in the market.

If we missed something on this list - let us know.