V3.1.0 rc0 release prep #2252
Closed
V3.1.0 rc0 release prep #2252
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
The specification recommends using semver for version specifications here: https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.1.md#versions
I would love to see my project added. Thank you.
Update README.md
Fix "current specification" link to point to latest release 3.0.2.
Fix "current specification" version
Registry/Pretty-Spec prep: Travis / package.json simplification
There is no way to tell a validator that a schema is using draft-wright-json-schema-validation-00, which is the only draft with a "uriref" format. Validators either interpret schemas as the previous draft (fge-04), which does not have this concept at all, or the following draft (wright-01) which has "uri-reference". Since there are no options that will automatically work correctly, using the later form seems to be the best. Many validators allow registering extensions, and we can just document that we are using the wright-01+ syntax. You often need to register format handlers to get *any* format validation with many validators anyway, so this does not seem overly burdensome.
Constructs such as:
type: object
not:
type: object
will always fail, so remove the type inside the not.
The "not" usage around "^x-" patterns for responses is
unnecessary, as the existing
patternProperties:
"[1-5]..."
additionalProperties: false
prevents all property that do not start with 1, 2, 3, 4, or 5
from being allowed already.
While draft-wright-json-schema-00 forbids JSON References except where a schema is expected, no validators implement this until draft-writght-json-schema-01. wright-00 schemas are in practice processed as draft-04 schemas, meaning that "$ref" is always considered a JSON Reference. Or, at least, some validators do that. We can work around this by using a pattern that only matches "$ref". There is no problem with the $ref in the "required" keyword, as only "$ref" as a property name is recognized as a reference.
Add PHP-CRUD-API
Implementations: add "kin-openapi"
Use semver for API version in example
Add API Sprout to new mock server section
…n pull request suggestion
Add Redoc to user interface implementations
* Addressing #1389, and clearing the way for PRs #2046 and #1977. This adds a formal proposal to clarify the semantics of nullable, providing the necessary background and links to related resources. * Corrected table formatting. * Minor tweaks and corrections. * Correct Change Log heading. * Cleaned up notes about translation to JSON Schema and *Of inheritance semantics. * Fix Change Log heading in the proposal template. * Snappy answers to stupid questions. * Change single-quote 'null' to double-quote "null" Thanks, @handrews for the review. * Clarified the proposed definition of nullable Somehow in our collaborative editing, we neglected to state that `nullable` adds `"null"` to the set of allowed types. We just said that it "expands" the `type` value, but didn't state the obvious (to us) manner of said expansion. Correcting that oversight in this commit. * Corrected the alternative, heavy-handed interpretation of nullable. * Added more explicit detail about the primary use case. * Added a more complete explanation of the problems created by disallowing nulls by default.
* Addressing #1389, and clearing the way for PRs #2046 and #1977. This adds a formal proposal to clarify the semantics of nullable, providing the necessary background and links to related resources. * Corrected table formatting. * Minor tweaks and corrections. * Correct Change Log heading. * Cleaned up notes about translation to JSON Schema and *Of inheritance semantics. * Fix Change Log heading in the proposal template. * Snappy answers to stupid questions. * Change single-quote 'null' to double-quote "null" Thanks, @handrews for the review. * Clarified the proposed definition of nullable Somehow in our collaborative editing, we neglected to state that `nullable` adds `"null"` to the set of allowed types. We just said that it "expands" the `type` value, but didn't state the obvious (to us) manner of said expansion. Correcting that oversight in this commit. * Corrected the alternative, heavy-handed interpretation of nullable. * Added more explicit detail about the primary use case. * Added a more complete explanation of the problems created by disallowing nulls by default. * Added issue #2057 - interactions between nullable and default value.
Missing the article 'a' in a few places.
Tiny corrections to proposal
Add spring-openapi to low-level tooling in IMPLEMENTATIONS.md
Add fastify oas
* Moved contents of overlay issue to a proposal document * Added overlay proposal * Updates based on feedback plus some scenarios
OpenAPI not Open API
* 3.0.3 prep * Update README.md * Update README.md * Removed confusing comment * Updated text for OperationRef * Clarified supported Ecma edition for regex Added supported Ecma edition (5.1) for regular expressions in the link text and used the formal name: [Ecma-262 Edition 5.1](https://www.ecma-international.org/ecma-262/5.1/). See also: #1687 * Make ABNF for runtime expressions complete * json-schema.org and commonmark.org now support https * Update 3.0.2.md fixed typo * Update 3.0.2.md fixed typo * Fixed typo * Update 3.0.3.md fixed typo * Update 3.0.2.md fixed typo * explicit 'forward slash' * add back quotes * fix difference between yaml and json in Response Object Examples * fix typo in Callback Object * Update 3.0.2.md * yaml.org supports https, but www.yaml.org is misconfigured * allow, but discourage, requestBody for GET, HEAD, DELETE * spelling error * retain typo in v3.0.2; fix for v3.0.3 (#1899) * Corrected pattern regex dialect link * TSC 2019-10-03 Feedback This sentance was meant to paraphrase semver for clarifty, but ended up suggesting a confusion situation where new things essentially cannot really happen. @webron has context on this. * Ron's wording for Darrels feedback * ted updates * backticks * Improved callback examples * fix #2053: `style` keyword is not supported inside Schema object * Resolved undocumented nullable behavior (#2046) * Resolved undocumented nullable behavior OpenAPI Schema Objects and JSON Schema have a few fundamental differences, and this clears up a bit of confusion about one of them. * Added ted updates from oct 31st TSC Co-Authored-By: Ted Epstein <ted.epstein@reprezen.com> * Update versions/3.0.3.md Co-Authored-By: Darrel <darrmi@microsoft.com> * Fix 'Security Scheme Object' definition with OAuth 2.0 grant types. (#2006) * The examples keyword is not supported inside schema (#2042) * examples not supported inside schema * figured it out * a tiny little edit * Replace 'application' by 'API' within the 'Info Object' definition. (#2004) * OpenAPI not Open API * Revert "allow, but discourage, requestBody for GET, HEAD, DELETE" * Clarify constraints on Security Scheme Object Scheme Property (#1880) * Wording around scheme extensions * Clarified that securitySchemeScheme is only a SHOULD be registered scheme * Fix formatting errors in example (#2132) * Server Variable Object clarifications (#1809) * Server Variable Object clarifications * Toned language down for proper semver versioning * Path Templating Clarification - proposed fix for #1830. (#1831) * Proposed fix for #1830. Each variable expression in a path must have a corresponding path parameter. * #1830 - Removed 'at least once' to defer the question about repeated references to a single path parameter. * Update #1830 fix with suggestion from Darrel @darrelmiller suggestions we use "template expression" instead of "variable expression" to align with RFC6570. Good idea. * Clarify the spec to allow optional or unspecified OAuth scopes (#1888) * Referencing issue #513. Clarify the spec to accommodate OAuth schemes where scope may be unspecified (optional scope) or where scope is not used at all. * Removed the provision for default scope represented as empty string. This introduces some ambiguities in the Security Requirement Object that would need to be addressed. * For #513, adjusting language and removing examples For #513, adjusting language and removing examples as suggested by @webron. * removed unnecessary example header Co-authored-by: Ron <ron@swagger.io> * Clarify empty Security Requirement Object usage and validity (#1886) * Clarify empty Security Requirement Object usage and validity * Reorder sentences to make clearer. * Remove wrong text. * Removed unneeded text. Co-authored-by: Ron <ron@swagger.io> * fix a typo in the Security Filtering section (#1837) * fix a typo in the Security Filtering section * Security filtering slight reword Co-authored-by: Mike Ralphson <mike.ralphson@gmail.com> * minor clarification for operationId usage in link objects (#1733) * minor clarification it's a bit confusing that both the id and the reference are called "operationId", so this tweak makes the text a bit more explicit. * use right terminology Co-Authored-By: Mike Ralphson <mike.ralphson@gmail.com> Co-authored-by: Ron <ron@swagger.io> Co-authored-by: Mike Ralphson <mike.ralphson@gmail.com> * Explain unclear semantics of property `$ref` in Path Item Object (#1964) * Explain unclear semantics of property `$ref` in Path Item Object Currently, as explained in #1038 (comment) the description of `$ref` in [Path Item Object](https://github.com/OAI/OpenAPI-Specification/blob/3.0.2/versions/3.0.2.md#pathItemObject) is unclear about the semantics behing it. I took the explaination from issue #1038 to make it more clear. * Update versions/3.0.3.md Co-authored-by: Ron <ron@swagger.io> * Update 3.0.3 for release (#2149) * Update README.md for release * Update release date for 3.0.3 Co-authored-by: Darrel <darrmi@microsoft.com> Co-authored-by: Mike Ralphson <mike.ralphson@gmail.com> Co-authored-by: Sergej <sergej2705@users.noreply.github.com> Co-authored-by: Seiya <r108338@yahoo.co.jp> Co-authored-by: Alan Crosswell <alan@crosswell.us> Co-authored-by: Rich Ellis <ricellis@users.noreply.github.com> Co-authored-by: Phil Sturgeon <me@philsturgeon.uk> Co-authored-by: nasa9084 <nasa9084@users.noreply.github.com> Co-authored-by: Ted Epstein <ted.epstein@reprezen.com> Co-authored-by: Patrice Krakow <patrice.krakow@gmail.com> Co-authored-by: Marsh Gardiner <marsh.gardiner@gmail.com> Co-authored-by: Henry Andrews <andrews_henry@yahoo.com> Co-authored-by: Sebastián Ramírez <tiangolo@gmail.com> Co-authored-by: Erik Wilde <dret@users.noreply.github.com> Co-authored-by: Carsten Brandt <mail@cebe.cc>
Fix broken YAML in examples/v3.0/api-with-examples.yaml
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.
TBD