When writing REST APIs the first thing to do before coding is to write the specification in OpenAPI or RAML format and then give it to the consumers of the API to gather feedback. You will discover that lot of things you though were good, need to be changed.

This approach also let’s you discover lots of flaws in your planning and design before you write any code.

The specification will also be interactive docs, because tools exist to transform the specification in a docs site where the API requests can be tested against a mock server built from the spec.

Any links to good resources on RAML Paulo?

Post updated with the links to both specifications.

RAML (Mulesoft specs) is now part of the OpenAPI initiative, therefore both specs can be exported to each other format.