Changing references from Swagger to OpenAPI where appropriate #572
Conversation
| @@ -1,26 +1,29 @@ | |||
| # OpenAPI Specification | |||
| ## (fka Swagger RESTful API Documentation Specification) | |||
| ## (Formerly-known-as the OpenAPI Specification) | |||
There was a problem hiding this comment.
I think this requires a careful review
|
I believe this was discussed before. The spec was donated, and the rename of 2.0 is more symbolic. Changing the entire references in the document serves little purpose and imho and will add to the confusion of our users - changing a name is not easy. More so, changing the The next version will be all OpenAPI Specification, there's no doubt about it, and hopefully we're not too far off from there. If you feel strongly that things need to be clarified, I'd be okay with adding a disclaimer at the top of the document saying that this spec was donated from the Swagger project and adopted by the OAI - references to the term "Swagger" can/should be considered as the "OpenAPI". I'm afraid I have to vote no for merging this as-is - I not only see no value in it, I strongly feel it is counterproductive. |
|
@webron As I understand it, we all agreed that the version declaration key of While the name of the project and title in this file have been changed to reflect the new name of the spec, much of the subsequent documentation still refers to Swagger in a way that I find confusing when I put on my new-user hat. The changes required even to this one file are obviously much more complicated than a simple find-and-replace, and I figured I could take a pass with some best-guesses. My big mistake was forgetting to explain better what I was trying to accomplish, a result of trying to sneak too much work in on a Friday night—my apologies! It should be a goal of the TDC that the spec and its documentation reflect a neutral position and not prefer tooling from any one vendor. I'd like to help with that process, and this is but a first attempt. I did try to keep references to Swagger where it was most appropriate, such as the version history and the The change to the reference to the spec is a good point, and so I should address that and re-submit, as I hadn't thought that through enough. If you have other observations about spec-altering edits, I'll absolutely address those as well and resubmit. |
| The Swagger specification defines a set of files required to describe such an API. These files can then be used by the Swagger-UI project to display the API and Swagger-Codegen to generate clients in various languages. Additional utilities can also take advantage of the resulting files, such as testing tools. | ||
| This project defines a set of files required to describe such an API. These files can then be used by tools to render API documentation or to generate client SDKs in various languages. Additional utilities can also take advantage of the resulting files, such as testing tools. | ||
|
|
||
| This is part of the OpenAPI Initiative (OAI), a collaboration between many companies under the auspices of the Linux Foundation. For more information on the initiative, its members, and its mandate, visit [OpenAPIs.org](http://openapis.org) The OpenAPI Specification grew out of the OpenAPI Specification that was donated to the OIA by SmartBear. |
There was a problem hiding this comment.
Hmm, the last sentence is not really correct. If you are editing the 2.0 document, then it should describe the 2.0 document, and this didn't "grew out of something", but "is identical to the Swagger Specification", so people know that it is the same.
In a text for the next version something like your sentence (with a reference to Swagger) would be more fitting.
There was a problem hiding this comment.
Yes, another miss. I need to go back through all of them again more carefully, just haven't made the time yet. Appreciate the 2nd set of eyes, though!
|
@earth2marsh can we close this? We can have a new one that you feel like is ready to review. |
| <a name="openapiInfo"></a>info | [Info Object](#infoObject) | **Required.** Provides metadata about the API. The metadata can be used by the clients if needed. | ||
| <a name="openapiHost"></a>host | `string` | The host (name or ip) serving the API. This MUST be the host only and does not include the scheme nor sub-paths. It MAY include a port. If the `host` is not included, the host serving the documentation is to be used (including the port). The `host` does not support [path templating](#pathTemplating). | ||
| <a name="openapiBasePath"></a>basePath | `string` | The base path on which the API is served, which is relative to the [`host`](#openapiHost). If it is not included, the API is served directly under the `host`. The value MUST start with a leading slash (`/`). The `basePath` does not support [path templating](#pathTemplating). | ||
| <a name="openapiSchemes"></a>schemes | [`string`] | The transfer protocol of the API. Values MUST be from the list: `"http"`, `"https"`, `"ws"`, `"wss"`. If the `schemes` is not included, the default scheme to be used is the one used to access the OpenAPI Specification's definition itself. |
There was a problem hiding this comment.
I think here we need to think about the wording. What is the "OpenAPI Specification", and what is its definition?
As I understand, the OpenAPI Specification is this document we are currently editing here. What is meant at this point is an API definition/documentation file (formerly known as "Swagger definition"), and I'm not sure how to call it. "OpenAPI definition"? It should be formally defined somewhere (I propose section "file structure").
|
It might get more helpful comments if it stays open, but if there are good On Wed, Feb 24, 2016, 12:13 PM Tony Tam notifications@github.com wrote:
|
|
with #597 merged can we close this, Marsh? |
|
@earth2marsh I believe per your wish, |
|
Absolutely. Thanks for the other changes. |
No description provided.