v3.2: Refactor and streamline OpenAPI Description Structure sections #4918
+184
−173
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
* Remove "OpenAPI Description" and "OpenAPI Document" section
headings and reorder those paragraphs and the intro
"OpenAPI Description Structure" paragraph to define the terms inline
* Switch Appendixes F and G
* F->G stays as-is, with base URI examples
* G->F is expanded to a more general
"Parsing and Resolution Guidance" section
* Move several pieces of "Parsing Documents" to Appendix G
* How to parse complete documents as the intro section
* A "Warnings Regarding Fragmentary Parsing" section
* Move "Structural Interoperability" under Appendix G and rename
it to "Conflicts Between Field Types and Reference Contexts"
* Move most of "Resolving Implicit Connections to Appendix G and
rename it "Guidance Regarding Implicit Connections"
* Put the original Section F implicit connection examples as
a "Implicit Connection Resolution Examples" subsection
Minimal adjustments were made to links to keep the build functional.
A lot of what was here is no longer needed, and other things can be said better either because of the new arrangement or because I thought of better wording since I first wrote things.
|
Note that despite my care to not overlap any changes, |
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.
Please review carefully, as there's more going on here than in the other reorg PRs.
These sections had gotten rather bloated, plus moving them under the OpenAPI Object changes how it all reads. These two commits first move things (with as few changes as possible) and then make significant edits to the results for conciseness and readability. None of the changes are intended to change any actual requirements.
While there are a lot of changes, there are also a lot of unchanged blocks, including the former Appendixes F and G which are now in reversed order and (in one case) a subsection of the new appendix. Here are
git diff --color-moved=dimmed-zebradiffs which make that a lot more clear (but are not good for detailed reviewing).1st commit message:
headings and reorder those paragraphs and the intro
"OpenAPI Description Structure" paragraph to define the terms inline
2nd commit message:
A lot of what was here is no longer needed, and other things can
be said better either because of the new arrangement or because
I thought of better wording since I first wrote things.