If you build a microwave, a specification tells how that microwave works; it includes the most important details and perhaps a list of requirements that the end product should fulfill. Once the microwave gets built, the user’s manual shows how to operate and maintain it. In a similar way, you need a specification when building an API.

An API description document, also known as API specification, is a technical document that tells how a system or program works, and shows a consumer how to work with the API. The API documentation shows how to use an API, and it will typically include a technical reference as well as functional guides for how to interact with the API across various use cases.

Web APIs have been around for almost 20 years, but in the last few years the API-first concept has gained traction among teams. An API-first approach means that for any software development project, its APIs are treated as “first class citizens”, and these “citizens” need to have good documents.

Besides generating code from an API specification file, it is also possible to generate and publish without costs its web documentation automatically using the GitHub ecosystem and other open-source tools.

This session will cover:

– Different ways to approach API design and documentation
– Reverse engineering to adopt the OpenAPI Specification
– How to create a CI/CD/CDoc workflow for your API documentation
– Open source tools to bundle, validate and lint an API description document
– Optimize your images and screenshots with open source tools
– Quickly and automagically generate a 3CL mobile-friendly documentation website
– Release and publish your API website without costs

The session is based on lessons learned and adopted best practices from different projects.