An OpenAPI description is human-readable metadata attached to an API or one of its elements. It explains intent, consumer-facing behavior, implementation checks, ordering conventions, and links to related artifacts. section 12.4.4 section 19.2.1
Use descriptions to make an API easier to understand and consume:
- Refine an operation’s wording to identify its primary REST resource: “Add to the catalog” points to Catalog, while “Remove a product” points to Product. section 3.3.3
- Document conventions that JSON Schema cannot formally express, such as sorting a balances array by value-date and then expected. section 8.6.3
- State authorization checks and visibility rules, including transfer limits and properties returned only to account owners. section 12.4.4
- Add Markdown changelogs, links to related artifacts, and tags that help consumers and design stakeholders find modified operations. section 15.7.3 section 19.2.1
Clarifying a money transfer operation
An operation description can state that some bank advisors cannot transfer more than $100,000 to an external account and that the implementation must return an error. A merchant property description can add: “Only returned to account owners.” Together, these descriptions expose both the permitted action and the resulting response differences. section 12.4.4
Figure 3.11 We can shorten the description to identify an operation’s resource.
Shorten an operation description when removing secondary concepts helps reveal the resource being manipulated. section 3.3.3
Figure 15.13 Use Markdown to add changelogs to the API and any element that supports description. Consider adding tags to highlight modified operations.
Use Markdown in description fields to present changelog entries and pair them with tags that highlight modified operations. section 15.7.3
