Have you ever found yourself in a situation where the API documentation was outdated or simply incorrect? This situation is mainly due to the fact that the documentation is either done after the fact or the generation tools are not suitable.

In the context of API development, we too often oppose Code-First approaches to API-First approaches. Most developers prefer the former because it is more code-centric and documentation is generated automatically. Unfortunately, the latter is often only associated with the words "documentation" or "specifications."

However, designing and implementing an API-First approach offers many advantages: ensuring that implementations are compatible with specifications, automating the validation of published APIs, and most importantly, enhancing the developer experience for your customers.

In this Tools in Action, we will transform an API developed in Java using Spring by shifting from "Code-First" to "API-First" using the latest practices and tools.

By adopting main API specifications such as JSONAPI and OpenAPI, and utilizing tools from the OpenAPI initiative like OpenAPI Generator and Microcks, we will therefore improve the design and software lifecycle .

Last but not least, we will explore how to tackle this major challenge: improving the quality of your API, encouraging its adoption by your clients, and, above all, getting your developers to enjoy writing and handling API documentation.