Standardize on "Description" as discussed on Slack #66
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
ralfhandl
reviewed
Sep 28, 2023
specification/structure.md
Outdated
|
|
||
| An OpenAPI document is a text file, commonly called `openapi.json` or `openapi.yaml`, representing a [JSON](https://en.wikipedia.org/wiki/JSON) object, in either JSON or [YAML](https://en.wikipedia.org/wiki/YAML) format. This file is called the **root document** and it can be split into multiple JSON or YAML files, for clarity. | ||
| OpenAPI Descriptions are written as one or more text documents, commonly called `openapi.json` or `openapi.yaml`, representing a [JSON](https://en.wikipedia.org/wiki/JSON) object, in either JSON or [YAML](https://en.wikipedia.org/wiki/YAML) format. This document is called the **root document**. An OAD can consist solely of a root document, or it can be split into multiple documents for clarity. |
There was a problem hiding this comment.
"one or more text documents" and "commonly called openapi.json" is a bit confusing.
Maybe first introduce the "entry document" and say that "the entry document is commonly called ..."
There was a problem hiding this comment.
@ralfhandl thanks, will do- this goes better with the "root OpenAPI document" -> "entry OpenAPI document" change in the other PRs, too.
ralfhandl
reviewed
Sep 28, 2023
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 * "documentation" only refers to generated or hand-written docs
Co-authored-by: Ralf Handl <[email protected]>
Also try to explain single vs multi documents and JSON objects, and the relationship of documents, references, and OADs, more clearly.
handrews
force-pushed
the
description
branch
from
4b5fbdc to
76df55d
Compare
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
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)