We know that a microservice is a self-contained component that performs some very specialized tasks with as much independence as possible.

But we also know that every component that we build has some kind of communication with other components (with rare exceptions). Usually, this communication happens through some kind of information sent and a response received. So, each service needs to know what should be sent to the other service and what kind of response is returned. Otherwise, this communication will have issues or even fail.

If you take care of both services or the people taking care of the other service are seated just behind you, fine. You just know it (or you just ask about it)! But things are completely different when you have dozens (hundreds or thousands) of microservices managed by teams distributed all over the world. Then, you'll need something more productive...

That's when API documentation comes to the rescue! And with Eclipse MicroProfile, this is pretty easy and is available right away through the implementation of OpenAPI, a well known open source project devoted to this matter. To get more details about it, visit https://www.openapis.org/.

This recipe will teach you how to document your service and how to see this documentation. I'll be able to provide useful information about your component in a way that anyone will be able to understand how it works.