Documentation

An API needs a proper documentation to help developers to use the API.

It is important to have a short but meaningful description about the purpose of the API.

Describe important use cases to give developers a quick headstart.

The goal is to enable a developer to use your API as quickly as possible:

• Enable a developer to use your API in 5 minutes
• Documentation is non-negotiable!

Use Swagger as description and definition language of your API.

Use Swagger to create API reference documentation.

We strongly advise against generating a API description from code. The only proper place for generating Swagger from code is for automated validation to validate that a API signature has not changed from one release to the next. See also Generating Swagger from Code for some practical advice.

Use an API Management Portal to allow developers to get familar and to test your API.