Home Blog ReviewsAbout

Which API documentation tools?

by Saulius - posted in: Reviews
Which API documentation tools should I use for my platform?

In the previous posts we took a close look at api gateway platforms and api testing tools and frameworks.

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

Documenting APIs

Treating your internal and public service APIs as products allows you to understand the business value and enables long term view on operating.

And every good technology product aim to provide its users helpful documentation and onboarding guides.

Below we have collected the list of most used API documentation tools and frameworks from the industry

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

The above references and collections should provide you with the overview of the most popular API documentation tools and frameworks.

Choose wisely and remember that maintaining API documentation and specifications requires engineering effort but pays tech organization wide dividends in the long run.

If you would like to recommend a framework or a tool to be added to above list - let us know.

Similar posts: