Api first and Api specification first platform development patterns are becoming important part of technology transformation efforts.
Treating your internal and public service Apis as products allows you to assess the business value and necessity before engaging into technology delivery efforts.
Every good technology product should aim to provide helpful documentation. Product adoption depends on it.
Moreover, in case of Api documentation, ideally it has to be understood by 2 types users – humans and machines.
Machine readable documentation allows automated generation of client libraries, SDKs and related developer tools. Important part of making software delivery agile.
Technology platforms which use microservices based architecture, usually use service catalogues for discovery.
It becomes very important to maintain such catalogues as the number of microservices on the platform grows.
Ideally, microservice catalogues should include Api documentation for each of the listed microservices.
This ensures faster communication between microservice owners, agile development lifecycles and significantly reduced number of integration faults.
Tools and Frameworks
In the below section I have summarised the list of most used Api documentation tools, specifications and frameworks.
Api documentation specifications
- 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 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 Initiative. Currently it’s just a promising initiative which might end up becoming a recognised specification. The focus is to provide clear interface definition for message driven communication between services.
- I/O Docs Definition. It’s an API specification format used by Tibco enterprise products. Not currently being developed. Nevertheless, you might come across it within some enterprise technology stacks.
Api documentation toolsets
- 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.
- OpenAPI tools. Is good collection of tools and frameworks to work with OpenAPI specification. Including schema validators, data validators etc.
- API Blueprint tools. Great list of API blueprint specification tools. Including parsers, renderers, mock servers 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.
- 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.
Api specification standardisation efforts
- OpenBanking. Is a prescriptive API specification accessing financial data and financial services. Licensed under MIT open source license.
The above references and collections should provide you with the overview of the most popular API documentation tools landscape.
There are many API documentation and specification tools and frameworks used across multiple technology platforms.
Choose wisely and remember that maintaining API documentation and specifications requires engineering effort.
Even for internal pool of microservices.