added version clarification #901
Conversation
|
LGTM. |
|
|
1 similar comment
|
|
| @@ -221,7 +222,7 @@ Field Name | Type | Description | |||
| <a name="infoTermsOfService"></a>termsOfService | `string` | A URL to the Terms of Service for the API. | |||
| <a name="infoContact"></a>contact | [Contact Object](#contactObject) | The contact information for the exposed API. | |||
| <a name="infoLicense"></a>license | [License Object](#licenseObject) | The license information for the exposed API. | |||
| <a name="infoVersion"></a>version | `string` | **Required** Provides the version of the application API (not to be confused with the specification version). | |||
| <a name="infoVersion"></a>version | `string` | **Required** Provides the version of the application API (not to be confused with the specification version). While not required, is it suggested that the `info.version` value correspond to the version of the API definition. In practice, the version of the API _implementation_ may evolve at an entirely different rate. | |||
There was a problem hiding this comment.
version is marked Requried, then the second sentence starts "While not required". Some may be confused and think this starts a contradiction. I suggest not adding this sentence at all, as it only raises additional questions (is "application API === "API definition"?) Instead, I suggest rephrasing, introducing fewer new/undefined/ambiguous terms:
Required Provides the version of the API (not to be confused with the OpenAPI specification version or the implementation version which may evolve at different rates).
There was a problem hiding this comment.
@DavidBiesack Would you please consider opening this as a separate issue or PR?
There was a problem hiding this comment.
@RobDolinMS - sure, see #905
versions/3.0.md
Outdated
| 1.1 | 2012-08-22 | Release of Swagger 1.1 | ||
| 1.0 | 2011-08-10 | First release of the Swagger Specification | ||
| --- | --- | --- | ||
| 3.0.0 | 2017-02-28 | Implementor's draft of the 3.0 specification |
There was a problem hiding this comment.
I suggest we follow a model of calling this v3.0.0-rc0 (release candidate zero) and then when we have polished, we're at v3.0.0-rc1 (or rc2 or rc3) and then we have a v3.0.0-final (and can delete the release candidates)
|
@OAI/tdc I've updated the version to be |
added version clarification
Partially addresses concern in #589