Describe OpenAPI entry point in OpenAPI description docs #3387
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
handrews
reviewed
Jan 26, 2024
versions/3.1.1.md
Outdated
| @@ -69,7 +69,7 @@ An OpenAPI definition can then be used by documentation generation tools to disp | |||
| ## Definitions | |||
|
|
|||
| ##### <a name="oasDocument"></a>OpenAPI Description | |||
| A document (or set of documents) that describes an API. An OpenAPI Description (OAD) uses and conforms to the OpenAPI Specification, and MUST contain at least one [paths](#pathsObject) field, [components](#oasComponents) field, or [webhooks](#oasWebhooks) field. | |||
| An OpenAPI description describes an API, and is composed of an [entry document](#documentStructure), and all its referenced documents. An OpenAPI Description (OAD) uses and conforms to the OpenAPI Specification, and MUST contain at least one [paths](#pathsObject) field, [components](#oasComponents) field, or [webhooks](#oasWebhooks) field. | |||
There was a problem hiding this comment.
Nitpick: Capitalize "Description" in "OpenAPI Description". You could then move the "(OAD)" up and just use OAD in the 2nd sentence.
Other than that, I think we just need to get some confirmation in a TDC meeting that folks are comfortable with "and all its referenced documents." It seems fine to me, but people have Opinons on this sort of thing.
handrews
added
the
clarification
ralfhandl
reviewed
Feb 1, 2024
Co-authored-by: Ralf Handl <[email protected]>
darrelmiller
approved these changes
Feb 1, 2024
ralfhandl
reviewed
Feb 1, 2024
Co-authored-by: Ralf Handl <[email protected]>
darrelmiller
approved these changes
Feb 1, 2024
lornajane
added a commit
to lornajane/OpenAPI-Specification
that referenced
this pull request
Apr 7, 2024
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.
Per discussion during the Sep 28 TDC meeting, this PR attempts to tease apart the identity of an OpenAPI description from the document(s) which comprise it.
It also references+links the entry point nomenclature, also settled-upon in same meeting.
💡 ❤️ I want to thank @handrews for their feedback during and after the meeting today. What I thought might be a trivial change is clearly a bit more nuanced than I expected and the space to think and refine the wording aided in my own understanding (and hopefully others' as well!)