Gittified and Powered-up API Docs

[David-Lazaro-Fernandez]

Ponente: Mᴀɴᴀsᴇ̄s Jᴇsᴜ̄s

"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 its web documentation automatically using the GitHub ecosystem and other open-source tools.

This session will cover:

• Different ways to approach an API creation and documentation

• How to create a CI/CD workflow for your API documentation

• Bundle, validate and lint an API description document

• Quickly and automagically generate a 3CL mobile-friendly documentation website

• Optimize your images and screenshots

• Release and publish your API website without costs"