How to produce and/or propose API documentation
REST
For these reasons the ModI imposes the use of OpenAPI v3. An OpenAPI file allows you to describe the entire interface (available endpoints and operations on each endpoint, input and output parameters for each operation, authentication methods, contact information, license, terms of use, etc.). |
3.9 Status Codes
3.9.4 Documentation of response payloads MUST NOT reveal internal implementation details of the server. |
| API Documentation |
Grammar Syntax
To provide a consistent developer experience across APIs and reduce learning curve, API designers must use the ISO 14977 Extended Backus-Naur Form (EBNF) syntax to define such grammars |
Output Fields
For fields that are output only, the field attribute shall be documented. |
Documentation
This section provides guidelines for adding inline documentation to your API. Most APIs will also have overviews, tutorials, and higher-level reference documentation, which are outside the scope of this Design Guide. |
Checklist for all descriptions
In most cases, there's more to say than just restating the obvious |
Options and link headers
In addition, services SHOULD include a Link header (see RFC 5988) to point to documentation for the resource |
Forms
... without referring to external documentation, an API user does not know what data to provide to operations that take input. |