changed swagger references #597
Conversation
versions/3.0.md
Outdated
| The OAS representation of the API is made of a single file. However, parts of the definitions can be split into separate files, at the discretion of the user. This is applicable for `$ref` fields in the specification as follows from the [JSON Schema](http://json-schema.org) definitions. | ||
|
|
||
| By convention, the Swagger specification file is named `swagger.json`. | ||
| By convention, the OAS specification file is named `swagger.json`. |
There was a problem hiding this comment.
I don't want to assume a new name at this point--will open in a separate issue
There was a problem hiding this comment.
Should be OAS not OAS specification.
|
@OAI/tdc please approve. This addresses #596 and is just a baseline for documentation changes |
versions/3.0.md
Outdated
| ### Schema | ||
|
|
||
| #### <a name="swaggerObject"></a>Swagger Object | ||
| #### <a name="oasObject"></a>OAS Object |
There was a problem hiding this comment.
The object name itself should probably be OpenAPI and not OAS in this case.
versions/3.0.md
Outdated
| <a name="oasInfo"></a>info | [Info Object](#infoObject) | **Required.** Provides metadata about the API. The metadata can be used by the clients if needed. | ||
| <a name="oasHost"></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="oasBasePath"></a>basePath | `string` | The base path on which the API is served, which is relative to the [`host`](#oasHost). 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="oasSchemes"></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 Swagger definition itself. |
There was a problem hiding this comment.
Description should change Swagger->OAS.
|
Overall reference changes look good. On top of the comments to the commits:
Obviously, we'll another run oh the spec before it's published to remove any additional unneeded referenced to Swagger. |
|
Curious as to terms. openapis.org uses "OAI specification" and "Open API Initiative" with a space in it. This github project uses "OpenAPI Specification" with no space. What is the official name of the specification: "OAI Specification", "Open API Specification" or "OpenAPI Specification" ? Is there a trademark pending? All the content should be consistent. This will also help with search optimization and bloggers and media will have a consistent term to use. |
|
@DavidBiesack - that's a fair point. I believe the differences are due to some relatively recent changes and the openapis.org page needs to be updated. For now, let's make sense of the terms. The The spec on the other hand is called the |
|
Thanks for the clarification/confirmation, @webron ...but I predict there will be lots of misue of the name (i.e. incorrectly written as "Open API Specification") on the intertubes as a result of this inconsistency, and we'll all groan every time we see it. You could head this all off and call it "Open API Specification"... Just a suggestion. |
versions/3.0.md
Outdated
| The OAS representation of the API is made of a single file. However, parts of the definitions can be split into separate files, at the discretion of the user. This is applicable for `$ref` fields in the specification as follows from the [JSON Schema](http://json-schema.org) definitions. | ||
|
|
||
| By convention, the Swagger specification file is named `swagger.json`. | ||
| By convention, the Open API Specification (OAS) file is named `swagger.json`. |
There was a problem hiding this comment.
Looks like a missed space on Open API (reference to OAS files are OpenAPI everywhere else).
|
Thanks @jasonh-n-austin. I'm going to merge this now, since nobody else has complianed, and i can revert if needed. |
Changed obvious references from Swagger to OpenAPI Specification and
OAI.