Help yourself when you code. Good design decisions make it easier to document your APIs. ...

Document from a user's perspective. ...

Don't put URIs front and center. ...

Write in a writing tool. ...

Generate examples automatically and combine them with your explanations. ...

Plan for the future

OpenAPI Specification (formerly called the Swagger

Specification).

The specification creates the RESTful

contract for your API, detailing all of its

resources and operations in a human

and machine readable format for easy

development, discovery, and

integration. 

https://springdoc.org/