How to produce and/or propose API documentation

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.
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
... without referring to external documentation, an API user does not know what data to provide to operations that take input.