From 5e974989fdd0d209b7183d8563a6864bef02c1ca Mon Sep 17 00:00:00 2001 From: Tony Tam Date: Thu, 6 Oct 2016 17:41:46 -0700 Subject: [PATCH 1/6] adds documentation on the openapi attribute and versioning strategy --- versions/3.0.md | 11 ++++++++++- 1 file changed, 10 insertions(+), 1 deletion(-) diff --git a/versions/3.0.md b/versions/3.0.md index 2e5bd3fda6..46c88003b5 100644 --- a/versions/3.0.md +++ b/versions/3.0.md @@ -125,7 +125,7 @@ It combines what previously was the Resource Listing and API Declaration (versio Field Name | Type | Description ---|:---:|--- -openapi | `string` | **Required.** Specifies the OpenAPI Specification version being used. It can be used by tooling Specifications and clients to interpret the version. The structure shall be `major`.`minor`.`patch`, where `patch` versions _must_ be compatible with the existing `major`.`minor` tooling. Typically patch versions will be introduced to address errors in the documentation, and tooling should typically be compatible with the corresponding `major`.`minor` (3.0.*). Patch versions will correspond to patches of this document. +openapi | [OpenAPI Version String](#oasVersion) | **Required.** Specifies the OpenAPI Specification version being used. It can be used by tooling Specifications and clients to interpret the version. The structure shall be `major`.`minor`.`patch`, where `patch` versions _must_ be compatible with the existing `major`.`minor` tooling. Typically patch versions will be introduced to address errors in the documentation, and tooling should typically be compatible with the corresponding `major`.`minor` (3.0.*). Patch versions will correspond to patches of this document. info | [Info Object](#infoObject) | **Required.** Provides metadata about the API. The metadata can be used by the clients if needed. hosts | [Hosts Object](#hostsObject) | An array of Host objects which provide `scheme`, `host`, `port`, and `basePath` in an associative manner. paths | [Paths Object](#pathsObject) | **Required.** The available paths and operations for the API. @@ -140,6 +140,15 @@ Field Pattern | Type | Description ---|:---:|--- ^x- | Any | Allows extensions to the OAS Schema. The field name MUST begin with `x-`, for example, `x-internal-id`. The value can be `null`, a primitive, an array or an object. See [Specification Extensions](#specificationExtensions) for further details. +#### OpenAPI Version String + +The version string signifies the version of the OpenAPI Specification that the document complies to. The format for this string _must_ be `major`.`minor`.`patch`. The `patch` _may_ be suffixed by a hyphen and extra alphanumeric characters. + +A `major`.`minor` shall be used to designate the OpenAPI Specification version, and will be considered compatible with the OpenAPI Specification specified by that `major`.`minor` version. The patch version will not be considered by tooling, making no distinction between `3.0.0` and `3.0.1`. + +In subsequent versions of the OpenAPI Specification, care will be given such that increments of the `minor` version should not interfere with operations of tooling developed to a lower minor version. Thus a hypothetical `3.1.0` specification should be usable with tooling designed for `3.0.0`. + + #### Info Object The object provides metadata about the API. From 2233066751cfbe2827cc138fb4b19be16db5f0be Mon Sep 17 00:00:00 2001 From: Tony Tam Date: Thu, 6 Oct 2016 19:46:51 -0700 Subject: [PATCH 2/6] added hosts setting --- versions/3.0.md | 72 ++++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 68 insertions(+), 4 deletions(-) diff --git a/versions/3.0.md b/versions/3.0.md index ae3bb390a8..f4506218f0 100644 --- a/versions/3.0.md +++ b/versions/3.0.md @@ -127,7 +127,7 @@ Field Name | Type | Description ---|:---:|--- openapi | [OpenAPI Version String](#oasVersion) | **Required.** Specifies the OpenAPI Specification version being used. It can be used by tooling Specifications and clients to interpret the version. The structure shall be `major`.`minor`.`patch`, where `patch` versions _must_ be compatible with the existing `major`.`minor` tooling. Typically patch versions will be introduced to address errors in the documentation, and tooling should typically be compatible with the corresponding `major`.`minor` (3.0.*). Patch versions will correspond to patches of this document. info | [Info Object](#infoObject) | **Required.** Provides metadata about the API. The metadata can be used by the clients if needed. -hosts | [Hosts Object](#hostsObject) | An array of Host objects which provide `scheme`, `host`, `port`, and `basePath` in an associative manner. +hosts | [Host Object](#hostObject) | An array of Host objects which provide connectivity information to a target host. paths | [Paths Object](#pathsObject) | **Required.** The available paths and operations for the API. components | [Components Object](#componentsObject) | An element to hold various schemas for the specification. security | [[Security Requirement Object](#securityRequirementObject)] | A declaration of which security schemes are applied for the API as a whole. The list of values describes alternative security schemes that can be used (that is, there is a logical OR between the security requirements). Individual operations can override this definition. @@ -205,9 +205,73 @@ An object representing a Host. Field Name | Type | Description ---|:---:|--- -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). -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). -scheme | `string` | The transfer protocol of the API. Values MUST be from the list: `"http"`, `"https"`, `"ws"`, `"wss"`. If the `scheme` is not included, the default scheme to be used is the one used to access the OpenAPI definition itself. +host URL template | `string` | A URL to the target host. This URL supports template variables and may be relative, to indicate that the host location is relative to the location where the OpenAPI Specification is being served. Templates are _optional_ and specified by the #hostTemplateParameter syntax. Template substitutions will be made when a variable is named in `{`brackets`}`. +host description | `string` | An optional string describing the host designated by the URL. +templates | [Templates Object](#hostTemplatesObject) | An object holding templates for substitution in the URL template + +This object can be extended with [Specification Extensions](#specificationExtensions). + +##### Host Object Example + +The following shows how multiple hosts can be described in the host object array + +```yaml +servers: +- url: https://development.gigantic-server.com/v1 + description: Development server +- url: https://staging.gigantic-server.com/v1 + description: Staging server +- url: https://api.gigantic-server.com/v1 + description: Production server +``` + +The following shows how templates an be used for a host configuration + +```yaml +servers: +- url: {scheme}://{host}:{port}/{basePath} + description: The production API server + templates: + scheme: + enum: + - https + - http + default: https + host: + enum: + - na1.gigantic-server.com + - na2.gigantic-server.com + port: + enum: + - 8443 + - 443 + default: 8443 + basePath: + default: v2 +``` + +#### Host Templates Object + +##### Patterned Fields + +Field Pattern | Type | Description +---|:---:|--- + [variable name] | [Host Template Parameter](#hostTemplateParameter) | A parameter to be used for substitution in the URL template. + +This object can be extended with [Specification Extensions](#specificationExtensions). + + +#### Host Template + +An object representing a Host URL template + +Field Name | Type | Description +---|:---:|--- +enum | [Possible Values] | An enumeration of primitive type values to be used if the substitution options are from a limited set. +default | [Default Value] | **Required.** The default value to use for substitution if an alternate value is not specified + +This object can be extended with [Specification Extensions](#specificationExtensions). + #### Contact Object From 1dbcb29ff82c38a79855c1445fed7e1cc8ae2087 Mon Sep 17 00:00:00 2001 From: Tony Tam Date: Thu, 6 Oct 2016 21:49:12 -0700 Subject: [PATCH 3/6] added items from #741 --- versions/3.0.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/versions/3.0.md b/versions/3.0.md index f4506218f0..3a2e3e4410 100644 --- a/versions/3.0.md +++ b/versions/3.0.md @@ -2023,6 +2023,9 @@ The following properties are taken from the JSON Schema definition but their def Their definition is the same as the one from JSON Schema, only where the original definition references the JSON Schema definition, the [Schema Object](#schemaObject) definition is used instead. - items - allOf +- oneOf +- anyOf +- not - properties - additionalProperties From 000a9a0f99f108b68ac49c5664b1e0323b102bf8 Mon Sep 17 00:00:00 2001 From: Tony Tam Date: Fri, 7 Oct 2016 09:58:05 -0700 Subject: [PATCH 4/6] moved it around, fixed example --- versions/3.0.md | 148 +++++++++++++++++++++++------------------------- 1 file changed, 72 insertions(+), 76 deletions(-) diff --git a/versions/3.0.md b/versions/3.0.md index 3a2e3e4410..178d40d225 100644 --- a/versions/3.0.md +++ b/versions/3.0.md @@ -127,7 +127,7 @@ Field Name | Type | Description ---|:---:|--- openapi | [OpenAPI Version String](#oasVersion) | **Required.** Specifies the OpenAPI Specification version being used. It can be used by tooling Specifications and clients to interpret the version. The structure shall be `major`.`minor`.`patch`, where `patch` versions _must_ be compatible with the existing `major`.`minor` tooling. Typically patch versions will be introduced to address errors in the documentation, and tooling should typically be compatible with the corresponding `major`.`minor` (3.0.*). Patch versions will correspond to patches of this document. info | [Info Object](#infoObject) | **Required.** Provides metadata about the API. The metadata can be used by the clients if needed. -hosts | [Host Object](#hostObject) | An array of Host objects which provide connectivity information to a target host. +hosts | [Server Object](#serverObject) | An array of Server Objects which provide connectivity information to a target host. paths | [Paths Object](#pathsObject) | **Required.** The available paths and operations for the API. components | [Components Object](#componentsObject) | An element to hold various schemas for the specification. security | [[Security Requirement Object](#securityRequirementObject)] | A declaration of which security schemes are applied for the API as a whole. The list of values describes alternative security schemes that can be used (that is, there is a logical OR between the security requirements). Individual operations can override this definition. @@ -197,23 +197,80 @@ license: version: 1.0.1 ``` -#### Host Object +#### Contact Object -An object representing a Host. +Contact information for the exposed API. ##### Fixed Fields Field Name | Type | Description ---|:---:|--- -host URL template | `string` | A URL to the target host. This URL supports template variables and may be relative, to indicate that the host location is relative to the location where the OpenAPI Specification is being served. Templates are _optional_ and specified by the #hostTemplateParameter syntax. Template substitutions will be made when a variable is named in `{`brackets`}`. +name | `string` | The identifying name of the contact person/organization. +url | `string` | The URL pointing to the contact information. MUST be in the format of a URL. +email | `string` | The email address of the contact person/organization. MUST be in the format of an email address. + +This object can be extended with [Specification Extensions](#specificationExtensions). + +##### Contact Object Example: + +```json +{ + "name": "API Support", + "url": "http://www.swagger.io/support", + "email": "support@swagger.io" +} +``` + +```yaml +name: API Support +url: http://www.swagger.io/support +email: support@swagger.io +``` + +#### License Object + +License information for the exposed API. + +##### Fixed Fields + +Field Name | Type | Description +---|:---:|--- +name | `string` | **Required.** The license name used for the API. +url | `string` | A URL to the license used for the API. MUST be in the format of a URL. + +This object can be extended with [Specification Extensions](#specificationExtensions). + +##### License Object Example: + +```json +{ + "name": "Apache 2.0", + "url": "http://www.apache.org/licenses/LICENSE-2.0.html" +} +``` + +```yaml +name: Apache 2.0 +url: http://www.apache.org/licenses/LICENSE-2.0.html +``` + +#### Server Object + +An object representing a Server. + +##### Fixed Fields + +Field Name | Type | Description +---|:---:|--- +server URL template | `string` | A URL to the target host. This URL supports template variables and may be relative, to indicate that the host location is relative to the location where the OpenAPI Specification is being served. Templates are _optional_ and specified by the #hostTemplateParameter syntax. Template substitutions will be made when a variable is named in `{`brackets`}`. host description | `string` | An optional string describing the host designated by the URL. templates | [Templates Object](#hostTemplatesObject) | An object holding templates for substitution in the URL template This object can be extended with [Specification Extensions](#specificationExtensions). -##### Host Object Example +##### Server Object Example -The following shows how multiple hosts can be described in the host object array +The following shows how multiple hosts can be described in the Server Object array ```yaml servers: @@ -225,28 +282,24 @@ servers: description: Production server ``` -The following shows how templates an be used for a host configuration +The following shows how templates an be used for a server configuration ```yaml servers: -- url: {scheme}://{host}:{port}/{basePath} +- url: https://{username}.gigantic-server.com:{port}/{basePath} description: The production API server templates: - scheme: - enum: - - https - - http - default: https - host: - enum: - - na1.gigantic-server.com - - na2.gigantic-server.com + username: + # note! no enum here means it is an open value + default: demo + description: this value is assigned by the service provider, in this example `gigantic-server.com` port: enum: - 8443 - 443 default: 8443 basePath: + # open meaning there is the opportunity to use special base paths as assigned by the provider, default is `v2` default: v2 ``` @@ -268,68 +321,11 @@ An object representing a Host URL template Field Name | Type | Description ---|:---:|--- enum | [Possible Values] | An enumeration of primitive type values to be used if the substitution options are from a limited set. -default | [Default Value] | **Required.** The default value to use for substitution if an alternate value is not specified +default | [Default Value] | **Required.** The default value to use for substitution if an alternate value is not specified, and will be sent if an alternative value is _not_ supplied. +description | `string` | An optional description for the template parameter This object can be extended with [Specification Extensions](#specificationExtensions). - -#### Contact Object - -Contact information for the exposed API. - -##### Fixed Fields - -Field Name | Type | Description ----|:---:|--- -name | `string` | The identifying name of the contact person/organization. -url | `string` | The URL pointing to the contact information. MUST be in the format of a URL. -email | `string` | The email address of the contact person/organization. MUST be in the format of an email address. - -This object can be extended with [Specification Extensions](#specificationExtensions). - -##### Contact Object Example: - -```json -{ - "name": "API Support", - "url": "http://www.swagger.io/support", - "email": "support@swagger.io" -} -``` - -```yaml -name: API Support -url: http://www.swagger.io/support -email: support@swagger.io -``` - -#### License Object - -License information for the exposed API. - -##### Fixed Fields - -Field Name | Type | Description ----|:---:|--- -name | `string` | **Required.** The license name used for the API. -url | `string` | A URL to the license used for the API. MUST be in the format of a URL. - -This object can be extended with [Specification Extensions](#specificationExtensions). - -##### License Object Example: - -```json -{ - "name": "Apache 2.0", - "url": "http://www.apache.org/licenses/LICENSE-2.0.html" -} -``` - -```yaml -name: Apache 2.0 -url: http://www.apache.org/licenses/LICENSE-2.0.html -``` - #### Components Object Holds a set of schemas for different aspects of the OAS. From a790e9ffb22e6698d2b2c708cdc65434f992763b Mon Sep 17 00:00:00 2001 From: Tony Tam Date: Fri, 7 Oct 2016 09:58:50 -0700 Subject: [PATCH 5/6] ooops --- versions/3.0.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/versions/3.0.md b/versions/3.0.md index 178d40d225..ff09457cca 100644 --- a/versions/3.0.md +++ b/versions/3.0.md @@ -127,7 +127,7 @@ Field Name | Type | Description ---|:---:|--- openapi | [OpenAPI Version String](#oasVersion) | **Required.** Specifies the OpenAPI Specification version being used. It can be used by tooling Specifications and clients to interpret the version. The structure shall be `major`.`minor`.`patch`, where `patch` versions _must_ be compatible with the existing `major`.`minor` tooling. Typically patch versions will be introduced to address errors in the documentation, and tooling should typically be compatible with the corresponding `major`.`minor` (3.0.*). Patch versions will correspond to patches of this document. info | [Info Object](#infoObject) | **Required.** Provides metadata about the API. The metadata can be used by the clients if needed. -hosts | [Server Object](#serverObject) | An array of Server Objects which provide connectivity information to a target host. +servers | [Server Object](#serverObject) | An array of Server Objects which provide connectivity information to a target server. paths | [Paths Object](#pathsObject) | **Required.** The available paths and operations for the API. components | [Components Object](#componentsObject) | An element to hold various schemas for the specification. security | [[Security Requirement Object](#securityRequirementObject)] | A declaration of which security schemes are applied for the API as a whole. The list of values describes alternative security schemes that can be used (that is, there is a logical OR between the security requirements). Individual operations can override this definition. From 5b5523765baab9a94eefb9ebb919166cb2958af2 Mon Sep 17 00:00:00 2001 From: Tony Tam Date: Fri, 7 Oct 2016 10:02:51 -0700 Subject: [PATCH 6/6] ooops --- versions/3.0.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/versions/3.0.md b/versions/3.0.md index ff09457cca..4fd462e98e 100644 --- a/versions/3.0.md +++ b/versions/3.0.md @@ -127,7 +127,7 @@ Field Name | Type | Description ---|:---:|--- openapi | [OpenAPI Version String](#oasVersion) | **Required.** Specifies the OpenAPI Specification version being used. It can be used by tooling Specifications and clients to interpret the version. The structure shall be `major`.`minor`.`patch`, where `patch` versions _must_ be compatible with the existing `major`.`minor` tooling. Typically patch versions will be introduced to address errors in the documentation, and tooling should typically be compatible with the corresponding `major`.`minor` (3.0.*). Patch versions will correspond to patches of this document. info | [Info Object](#infoObject) | **Required.** Provides metadata about the API. The metadata can be used by the clients if needed. -servers | [Server Object](#serverObject) | An array of Server Objects which provide connectivity information to a target server. +servers | [[Server Object](#serverObject)] | An optional array of Server Objects which provide connectivity information to a target server. paths | [Paths Object](#pathsObject) | **Required.** The available paths and operations for the API. components | [Components Object](#componentsObject) | An element to hold various schemas for the specification. security | [[Security Requirement Object](#securityRequirementObject)] | A declaration of which security schemes are applied for the API as a whole. The list of values describes alternative security schemes that can be used (that is, there is a logical OR between the security requirements). Individual operations can override this definition. @@ -262,7 +262,7 @@ An object representing a Server. Field Name | Type | Description ---|:---:|--- -server URL template | `string` | A URL to the target host. This URL supports template variables and may be relative, to indicate that the host location is relative to the location where the OpenAPI Specification is being served. Templates are _optional_ and specified by the #hostTemplateParameter syntax. Template substitutions will be made when a variable is named in `{`brackets`}`. +server URL template | `string` | A URL to the target host. This URL supports template variables and may be relative, to indicate that the host location is relative to the location where the OpenAPI Specification is being served. Templates are _optional_ and specified by the [#hostTemplateParameter] syntax. Template substitutions will be made when a variable is named in `{`brackets`}`. host description | `string` | An optional string describing the host designated by the URL. templates | [Templates Object](#hostTemplatesObject) | An object holding templates for substitution in the URL template