API Documentation is important technical content that includes instructions on how to effectively use it and provides information about the API’s lifecycle, such as new version and retirement.

Below you can see sections that an API documentation should have to provide minimum and helpful information.

1. Resource description
2. Endpoint
3. Parameters
4. Schema
5. Request Example
6. Response Example

Besides these sections, the documentation must be available for all stakeholders or even on the internet if you are writing a public API.

With this in mind, we can use pretty much any Content Management System or Static Site Generator, but there are better ways :)

Spring REST Docs and Open API 3.0 are the most popular ways to create API documentation, and they use substantially different approaches.

Spring REST Docs is a framework to create precise documentation. The philosophy behind the project is the use of tests to produce the documentation and ensure that the documentation is always generated precisely and matches the actual behavior of the API.

Once a test is executed, an AsciiDoc file will be generated, which can be used to generate an HTML page describing the entire API.

On the other side, we have OpenAPI(former Swagger). This is a specification, and all implementors should produce documentation in JSON or YAML format, which is basically generated based on the annotations from our controllers.

Many tools use the JSON/YAML to produce a UI where we can visualize, navigate and interact with each endpoint, which helps with the acceptance tests.