Release v3.0.4 #4080
Draft
Release v3.0.4 #4080
+4,369
−1
Conversation
This file contains 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
Clarifies that there can be multiple complete OpenAPI documents, only one of which is an entry OpenAPI document.
Clarify entry/complete document terminology (3.0.4)
Co-authored-by: Mike Kistler <mikekistler@microsoft.com>
Clarify discriminator "*Of" and "mapping" usage (3.0.4)
This acknowledges the ambiguity in the key and value syntax of the Link Object's `parameter` field, and provides a bit of guidance on how to implement it. Sadly it is not possible to fully solve in a point release.
Co-authored-by: Ralf Handl <ralf.handl@sap.com>
This aligns allowReserved with style by similarly correlating it with RFC6570 operators. This will make it easier to write a more in-depth explanation of the process in an appendix.
This is the one of several appendixes to be added to clarify the most obscure details of Parameter Object and Encoding Object serialization. This clarifies the correspondence between OAS fields and RFC6570 operators, and acknowledges that some field values and combinations do not have analogues. It provides further guidance for how to use RFC6570 implementations to support these configurations. This includes a SHOULD directive regarding using RFC6570 expansion with the non-RFC6570 styles, as the use of "explode" and "allowReserved" does not otherwise make any sense. It perhaps could be a MUST. Examples are included to show both typical usage, and how to work around the lack of exact RFC6570 equivalences for certain configurations.
Note that they are resolved in their rendered context.
RFC6570-based serialization will not go beyond what is specified to unpack arrays and objects.
Co-authored-by: Ralf Handl <ralf.handl@sap.com>
Co-authored-by: Darrel <darrmi@microsoft.com>
* Paramter names don't need to be modeled as template variables. * Include an example of a parameter name that needs encoding. * Add more details to the fixed field entries for allowReserved
Guide readers to supplemental documentation, examples, related specificatioins, and extension registries. These sites answer many questions that otherwise get raised as GitHub issues.
* Replace the outdated "model" terminology with "schema" * Remove the outdated `text/plain` array example, which does not correlate with current OAS requirements * Rather than replacing the `text/plain` example direclty, enhance the example of serializing `application/json` content in `application/x-www-form-urlencoeded` request bodies.
Co-authored-by: Ralf Handl <ralf.handl@sap.com>
Co-authored-by: Ralf Handl <ralf.handl@sap.com>
This copies the relevant Parameter Object fields to the Header Object instead of relying on implicit guidance. The text for the fields has been edited to reflect that only headers are being described. This also include an example of describing a header using the `content` field, and explaining why it is necessary to do so.
...to placate the PR checks in GitHub.
Co-authored-by: Ralf Handl <ralf.handl@sap.com>
Co-authored-by: Ralf Handl <ralf.handl@sap.com>
3.0.4: port the undisputed parts of #2140
There are even more ways this can go wrong!
3.0.4: update from main
* Explicitly set `explode: false` in an example as the default with `style: form` is `explode: true`; the `explode: true` example was also left explicit to reduce confusion. * Tidy up overly conversational (e.g. "our document") language that I'd meant to revisit but forgot about. * Include the Header Object as one of the places where the `style` keyword is used (even if it is the simplest case) * Minor grammar fix. * Fix a missing space before an RFC reference.
Style guide conformance.
Also give Appendix C a better name because it is relevant whether you are using an actual RFC6570 implementation or not.
Further guidance on RFC6570 and delimiters
Further clarify link operation ambiguity (3.0.4)
Clarify complete vs self-contained documents
Minor param serialization and wording fixes
The extended example with a multi-document OAD and a Security Requirement in the referenced document did to fit well where it was, and there wasn't room in the Resolving Implicit Connections area. So this moves it to an Appendix linked from both locations.
Move complex Sec Req example to appendix F
darrelmiller
previously approved these changes
Sep 16, 2024
limck5856
approved these changes
Sep 19, 2024
limck5856
approved these changes
Sep 19, 2024
3.0.4: use specific custom languages uri and uritemplate
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.
This PR will merge
v3.0.4-devintomain.Still to do: