The learn site previously decided to use OpenAPI Description, but hedged with terms like "OpenAPI Description document" and often reverted to "OpenAPI document" in the text.
A recent discussion on Slack finally revealed a consensus that
Re-defining "document" away from its intuitive meaning as a single coherent thing (file or network resource) is confusing
"description" has more support than "definition" or "document"
Following up on that discussion, this change standardizes on:
"OpenAPI Description" as the term for the logical entity
"OAD" as a standardized abbreviation, alongside OAS and OAI
"document" to mean either local file or network resource (mostly avoiding "file", although I could go either way on that)
"documentation" only refers to generated or hand-written docs
I'd like to add a glossary as well to clarify this, acknowledge the history, and clarify a few other bits of terminology, but I will do that in a follow-up PR if this PR or something like it gets accepted.
See also PR OAI/OpenAPI-Specification#3384 (3.0.4) and PR OAI/OpenAPI-Specification#3385 (3.1.1)
The learn site previously decided to use OpenAPI Description, but hedged with terms like "OpenAPI Description document" and often reverted to "OpenAPI document" in the text.
A recent discussion on Slack finally revealed a consensus that
Following up on that discussion, this change standardizes on:
I'd like to add a glossary as well to clarify this, acknowledge the history, and clarify a few other bits of terminology, but I will do that in a follow-up PR if this PR or something like it gets accepted.
See also PR OAI/OpenAPI-Specification#3384 (3.0.4) and PR OAI/OpenAPI-Specification#3385 (3.1.1)