Documentation

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.4 Documentation of response payloads MUST NOT reveal internal implementation details of the server.

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

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.

In most cases, there's more to say than just restating the obvious

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.