From ccf4651b206502fb1e11daf8f93bacdc76502d92 Mon Sep 17 00:00:00 2001 From: Marsh Gardiner Date: Fri, 30 Jun 2017 13:10:40 -0700 Subject: [PATCH 1/4] Prefer `description` when referring to an OAS document Usage of description and definition to refer to an OAS document was mixed. This makes it more consistent, and prefers "description" of the service, since as a possible-truth it is more broad than "definition," which suggests an actual truth. (note: definition does still occur in the doc, but those refer to specific parts of the document rather than the document as a whole) --- versions/3.0.md | 26 +++++++++++++------------- 1 file changed, 13 insertions(+), 13 deletions(-) diff --git a/versions/3.0.md b/versions/3.0.md index 0e6565f2ae..db7c84c728 100644 --- a/versions/3.0.md +++ b/versions/3.0.md @@ -8,15 +8,15 @@ This document is licensed under [The Apache License, Version 2.0](http://www.apa ## Introduction -The OpenAPI Specification (OAS) defines a standard, language-agnostic interface to RESTful APIs which allows both humans and computers to discover and understand the capabilities of the service without access to source code, documentation, or through network traffic inspection. When properly defined, a consumer can understand and interact with the remote service with a minimal amount of implementation logic. +The OpenAPI Specification (OAS) defines a standard, language-agnostic interface to RESTful APIs which allows both humans and computers to discover and understand the capabilities of the service without access to source code, documentation, or through network traffic inspection. When properly described, a consumer can understand and interact with the remote service with a minimal amount of implementation logic. -An OpenAPI definition can then be used by documentation generation tools to display the API, code generation tools to generate servers and clients in various programming languages, testing tools and many other use cases. +An OpenAPI description can then be used by documentation generation tools to display the API, code generation tools to generate servers and clients in various programming languages, testing tools and many other use cases. ## Table of Contents - [Definitions](#definitions) - - [OpenAPI Definition](#oasDefinition) + - [OpenAPI Description](#oasDescription) - [Path Templating](#pathTemplating) - [Media Types](#mediaTypes) - [HTTP Status Codes](#httpCodes) @@ -66,8 +66,8 @@ An OpenAPI definition can then be used by documentation generation tools to disp ## Definitions -##### OpenAPI Definition -A document or set of documents which defines an API. An OpenAPI definition uses and conforms to the OpenAPI Specification. +##### OpenAPI Description +A document or set of documents that describe an API. An OpenAPI description uses and conforms to the OpenAPI Specification. ##### Path Templating Path templating refers to the usage of curly braces ({}) to mark a section of a URL path as replaceable using path parameters. @@ -103,7 +103,7 @@ The `major`.`minor` portion of the semver (for example `3.0`) SHALL designate th Subsequent minor version releases of the OpenAPI Specification (incrementing the `minor` version number) SHOULD NOT interfere with tooling developed to a lower minor version and same major version. Thus a hypothetical `3.1.0` specification SHOULD be usable with tooling designed for `3.0.0`. -An OpenAPI definition compatible with OAS 3.\*.\* contains a required [`openapi`](#oasVersion) field which designates the semantic version of the OAS that it uses. (OAS 2.0 definition documents contain a top-level version field named [`swagger`](http://swagger.io/specification/#swaggerObject) and value `"2.0"`.) +An OpenAPI description compatible with OAS 3.\*.\* contains a required [`openapi`](#oasVersion) field which designates the semantic version of the OAS that it uses. (OAS 2.0 description documents contain a top-level version field named [`swagger`](http://swagger.io/specification/#swaggerObject) and value `"2.0"`.) ### Format @@ -131,11 +131,11 @@ In order to preserve the ability to round-trip between YAML and JSON formats, YA ### Document Structure -An OpenAPI definition MAY be made up of a single document. -However, parts of the definitions MAY be split into separate documents, at the discretion of the user. +An OpenAPI description MAY be made up of a single document. +However, parts of the description MAY be split into separate documents, 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. -It is RECOMMENDED that the root OpenAPI definition document be named: `openapi.json` or `openapi.yaml`. +It is RECOMMENDED that the root OpenAPI description document be named: `openapi.json` or `openapi.yaml`. ### Data Types @@ -183,13 +183,13 @@ In the following description, if a field is not explicitly **REQUIRED** or descr #### OpenAPI Object -This is the root document object of the [OpenAPI definition](#oasDefinition). +This is the root document object of the [OpenAPI description](#oasDescription). ##### Fixed Fields Field Name | Type | Description ---|:---:|--- -openapi | `string` | **REQUIRED**. This string MUST be the [semantic version number](http://semver.org/spec/v2.0.0.html) of the [OpenAPI Specification version](#versions) that the OpenAPI definition uses. The `openapi` field SHOULD be used by tooling specifications and clients to interpret the OpenAPI definition. This is *not* related to the API [`info.version`](#infoVersion) string. +openapi | `string` | **REQUIRED**. This string MUST be the [semantic version number](http://semver.org/spec/v2.0.0.html) of the [OpenAPI Specification version](#versions) that the OpenAPI description uses. The `openapi` field SHOULD be used by tooling specifications and clients to interpret the OpenAPI description. This is *not* related to the API [`info.version`](#infoVersion) string. 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. If the `servers` property is not provided, or is an empty array, the default value would be a [Server Object](#serverObject) with a [url](#serverUrl) value of `/`. paths | [Paths Object](#pathsObject) | **REQUIRED**. The available paths and operations for the API. @@ -214,7 +214,7 @@ Field Name | Type | Description termsOfService | `string` | A URL to the Terms of Service for the API. MUST be in the format of a URL. contact | [Contact Object](#contactObject) | The contact information for the exposed API. license | [License Object](#licenseObject) | The license information for the exposed API. -version | `string` | **REQUIRED**. The version of the API definition (which is distinct from the [OpenAPI Specification version](#oasVersion) or the API implementation version). +version | `string` | **REQUIRED**. The version of the API description (which is distinct from the [OpenAPI Specification version](#oasVersion) or the API implementation version). This object can be extended with [Specification Extensions](#specificationExtensions). @@ -318,7 +318,7 @@ An object representing a Server. Field Name | Type | Description ---|:---:|--- -url | `string` | **REQUIRED**. A URL to the target host. This URL supports Server Variables and MAY be relative, to indicate that the host location is relative to the location where the OpenAPI definition is being served. Variable substitutions will be made when a variable is named in `{`brackets`}`. +url | `string` | **REQUIRED**. A URL to the target host. This URL supports Server Variables and MAY be relative, to indicate that the host location is relative to the location where the OpenAPI description is being served. Variable substitutions will be made when a variable is named in `{`brackets`}`. description | `string` | An optional string describing the host designated by the URL. [CommonMark syntax](http://spec.commonmark.org/) can be used for rich text representation. variables | Map[`string`, [Server Variable Object](#serverVariableObject)] | A map between a variable name and its value. The value is used for substitution in the server's URL template. From 16e7257d3303768d092aa46489c8d132f94ea44e Mon Sep 17 00:00:00 2001 From: Marsh Gardiner Date: Fri, 7 Jul 2017 12:20:32 -0700 Subject: [PATCH 2/4] Use `document` in place of `description` or `definition` --- versions/3.0.md | 32 ++++++++++++++++---------------- 1 file changed, 16 insertions(+), 16 deletions(-) diff --git a/versions/3.0.md b/versions/3.0.md index db7c84c728..9372561139 100644 --- a/versions/3.0.md +++ b/versions/3.0.md @@ -8,15 +8,15 @@ This document is licensed under [The Apache License, Version 2.0](http://www.apa ## Introduction -The OpenAPI Specification (OAS) defines a standard, language-agnostic interface to RESTful APIs which allows both humans and computers to discover and understand the capabilities of the service without access to source code, documentation, or through network traffic inspection. When properly described, a consumer can understand and interact with the remote service with a minimal amount of implementation logic. +The OpenAPI Specification (OAS) defines a standard, language-agnostic interface to RESTful APIs which allows both humans and computers to discover and understand the capabilities of the service without access to source code, documentation, or through network traffic inspection. When properly documented, a consumer can understand and interact with the remote service with a minimal amount of implementation logic. -An OpenAPI description can then be used by documentation generation tools to display the API, code generation tools to generate servers and clients in various programming languages, testing tools and many other use cases. +An OpenAPI document can then be used by documentation generation tools to display the API, code generation tools to generate servers and clients in various programming languages, testing tools and many other use cases. ## Table of Contents - [Definitions](#definitions) - - [OpenAPI Description](#oasDescription) + - [OpenAPI Document](#oasDocument) - [Path Templating](#pathTemplating) - [Media Types](#mediaTypes) - [HTTP Status Codes](#httpCodes) @@ -66,8 +66,8 @@ An OpenAPI description can then be used by documentation generation tools to dis ## Definitions -##### OpenAPI Description -A document or set of documents that describe an API. An OpenAPI description uses and conforms to the OpenAPI Specification. +##### OpenAPI Document +A document or set of files that document an API. An OpenAPI document uses and conforms to the OpenAPI Specification. ##### Path Templating Path templating refers to the usage of curly braces ({}) to mark a section of a URL path as replaceable using path parameters. @@ -103,11 +103,11 @@ The `major`.`minor` portion of the semver (for example `3.0`) SHALL designate th Subsequent minor version releases of the OpenAPI Specification (incrementing the `minor` version number) SHOULD NOT interfere with tooling developed to a lower minor version and same major version. Thus a hypothetical `3.1.0` specification SHOULD be usable with tooling designed for `3.0.0`. -An OpenAPI description compatible with OAS 3.\*.\* contains a required [`openapi`](#oasVersion) field which designates the semantic version of the OAS that it uses. (OAS 2.0 description documents contain a top-level version field named [`swagger`](http://swagger.io/specification/#swaggerObject) and value `"2.0"`.) +An OpenAPI document compatible with OAS 3.\*.\* contains a required [`openapi`](#oasVersion) field which designates the semantic version of the OAS that it uses. (OAS 2.0 documents contain a top-level version field named [`swagger`](http://swagger.io/specification/#swaggerObject) and value `"2.0"`.) ### Format -An API description that conforms to the OpenAPI Specification is itself a JSON object, which may be represented either in JSON or YAML format. +An OpenAPI document that conforms to the OpenAPI Specification is itself a JSON object, which may be represented either in JSON or YAML format. For example, if a field has an array value, the JSON array representation will be used: @@ -127,22 +127,22 @@ In order to preserve the ability to round-trip between YAML and JSON formats, YA - Tags MUST be limited to those allowed by the [JSON Schema ruleset](http://www.yaml.org/spec/1.2/spec.html#id2803231). - Keys used in YAML maps MUST be limited to a scalar string, as defined by the [YAML Failsafe schema ruleset](http://yaml.org/spec/1.2/spec.html#id2802346). -**Note:** While APIs are described by OpenAPI documents in YAML or JSON format, the API request and response bodies and other content are not required to be JSON or YAML. +**Note:** While APIs may be described by OpenAPI documents in YAML or JSON format, the API request and response bodies and other content are not required to be JSON or YAML. ### Document Structure -An OpenAPI description MAY be made up of a single document. -However, parts of the description MAY be split into separate documents, at the discretion of the user. +An OpenAPI document MAY be made up of a single document. +However, parts of the document MAY 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. -It is RECOMMENDED that the root OpenAPI description document be named: `openapi.json` or `openapi.yaml`. +It is RECOMMENDED that the root OpenAPI document be named: `openapi.json` or `openapi.yaml`. ### Data Types Primitive data types in the OAS are based on the types supported by the [JSON Schema Specification Wright Draft 00](https://tools.ietf.org/html/draft-wright-json-schema-00#section-4.2). Note that `integer` as a type is also supported and is defined as a JSON number without a fraction or exponent part. `null` is not supported as a type (see [`nullable`](#schemaNullable) for an alternative solution). -Models are described using the [Schema Object](#schemaObject) which is an extended subset of JSON Schema Specification Wright Draft 00. +Models are defined using the [Schema Object](#schemaObject), which is an extended subset of JSON Schema Specification Wright Draft 00. Primitives have an optional modifier property: `format`. OAS uses several known formats to define in fine detail the data type being used. @@ -183,13 +183,13 @@ In the following description, if a field is not explicitly **REQUIRED** or descr #### OpenAPI Object -This is the root document object of the [OpenAPI description](#oasDescription). +This is the root document object of the [OpenAPI document](#oasDocument). ##### Fixed Fields Field Name | Type | Description ---|:---:|--- -openapi | `string` | **REQUIRED**. This string MUST be the [semantic version number](http://semver.org/spec/v2.0.0.html) of the [OpenAPI Specification version](#versions) that the OpenAPI description uses. The `openapi` field SHOULD be used by tooling specifications and clients to interpret the OpenAPI description. This is *not* related to the API [`info.version`](#infoVersion) string. +openapi | `string` | **REQUIRED**. This string MUST be the [semantic version number](http://semver.org/spec/v2.0.0.html) of the [OpenAPI Specification version](#versions) that the OpenAPI document uses. The `openapi` field SHOULD be used by tooling specifications and clients to interpret the OpenAPI document. This is *not* related to the API [`info.version`](#infoVersion) string. 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. If the `servers` property is not provided, or is an empty array, the default value would be a [Server Object](#serverObject) with a [url](#serverUrl) value of `/`. paths | [Paths Object](#pathsObject) | **REQUIRED**. The available paths and operations for the API. @@ -214,7 +214,7 @@ Field Name | Type | Description termsOfService | `string` | A URL to the Terms of Service for the API. MUST be in the format of a URL. contact | [Contact Object](#contactObject) | The contact information for the exposed API. license | [License Object](#licenseObject) | The license information for the exposed API. -version | `string` | **REQUIRED**. The version of the API description (which is distinct from the [OpenAPI Specification version](#oasVersion) or the API implementation version). +version | `string` | **REQUIRED**. The version of the OpenAPI document (which is distinct from the [OpenAPI Specification version](#oasVersion) or the API implementation version). This object can be extended with [Specification Extensions](#specificationExtensions). @@ -318,7 +318,7 @@ An object representing a Server. Field Name | Type | Description ---|:---:|--- -url | `string` | **REQUIRED**. A URL to the target host. This URL supports Server Variables and MAY be relative, to indicate that the host location is relative to the location where the OpenAPI description is being served. Variable substitutions will be made when a variable is named in `{`brackets`}`. +url | `string` | **REQUIRED**. A URL to the target host. This URL supports Server Variables and MAY be relative, to indicate that the host location is relative to the location where the OpenAPI document is being served. Variable substitutions will be made when a variable is named in `{`brackets`}`. description | `string` | An optional string describing the host designated by the URL. [CommonMark syntax](http://spec.commonmark.org/) can be used for rich text representation. variables | Map[`string`, [Server Variable Object](#serverVariableObject)] | A map between a variable name and its value. The value is used for substitution in the server's URL template. From 37ddaf2f335ef4773438bb228484abb6106646c8 Mon Sep 17 00:00:00 2001 From: Marsh Gardiner Date: Fri, 21 Jul 2017 07:33:47 -0700 Subject: [PATCH 3/4] Addressing comments MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This attempts to use `document` in its various forms when discussing the artifact (replaces `file` in the most part), though I tried to avoid mixing the file-like instances with the API documentation ones. Some instances have been changed to use `define` (or similar forms), though based on the comments suggesting that both `definition` and `description` are used in common parlance, `description` has not been fully expunged—hopefully this is a reasonable middle ground, but if upon review there is strong support for that, I'll re-submit. --- versions/3.0.md | 12 +++++------- 1 file changed, 5 insertions(+), 7 deletions(-) diff --git a/versions/3.0.md b/versions/3.0.md index 9372561139..037b202965 100644 --- a/versions/3.0.md +++ b/versions/3.0.md @@ -8,9 +8,9 @@ This document is licensed under [The Apache License, Version 2.0](http://www.apa ## Introduction -The OpenAPI Specification (OAS) defines a standard, language-agnostic interface to RESTful APIs which allows both humans and computers to discover and understand the capabilities of the service without access to source code, documentation, or through network traffic inspection. When properly documented, a consumer can understand and interact with the remote service with a minimal amount of implementation logic. +The OpenAPI Specification (OAS) defines a standard, language-agnostic interface to RESTful APIs which allows both humans and computers to discover and understand the capabilities of the service without access to source code, documentation, or through network traffic inspection. When properly defined, a consumer can understand and interact with the remote service with a minimal amount of implementation logic. -An OpenAPI document can then be used by documentation generation tools to display the API, code generation tools to generate servers and clients in various programming languages, testing tools and many other use cases. +An OpenAPI definition can then be used by documentation generation tools to display the API, code generation tools to generate servers and clients in various programming languages, testing tools, and many other use cases. ## Table of Contents @@ -67,7 +67,7 @@ An OpenAPI document can then be used by documentation generation tools to displa ## Definitions ##### OpenAPI Document -A document or set of files that document an API. An OpenAPI document uses and conforms to the OpenAPI Specification. +A document (or set of documents) that define or describe an API. An OpenAPI document uses and conforms to the OpenAPI Specification. ##### Path Templating Path templating refers to the usage of curly braces ({}) to mark a section of a URL path as replaceable using path parameters. @@ -127,13 +127,11 @@ In order to preserve the ability to round-trip between YAML and JSON formats, YA - Tags MUST be limited to those allowed by the [JSON Schema ruleset](http://www.yaml.org/spec/1.2/spec.html#id2803231). - Keys used in YAML maps MUST be limited to a scalar string, as defined by the [YAML Failsafe schema ruleset](http://yaml.org/spec/1.2/spec.html#id2802346). -**Note:** While APIs may be described by OpenAPI documents in YAML or JSON format, the API request and response bodies and other content are not required to be JSON or YAML. +**Note:** While APIs may be defined by OpenAPI documents in either YAML or JSON format, the API request and response bodies and other content are not required to be JSON or YAML. ### Document Structure -An OpenAPI document MAY be made up of a single document. -However, parts of the document MAY 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. +An OpenAPI document MAY be made up of a single document or be divided into multiple, connected parts at the discretion of the user. In the latter case, `$ref` fields MUST be used in the specification to reference those parts as follows from the [JSON Schema](http://json-schema.org) definitions. It is RECOMMENDED that the root OpenAPI document be named: `openapi.json` or `openapi.yaml`. From 000e5693b83667532b5728316bacc18b6fe1e7c5 Mon Sep 17 00:00:00 2001 From: Marsh Gardiner Date: Fri, 21 Jul 2017 09:30:13 -0700 Subject: [PATCH 4/4] Fixing verb agreement, reverting one instance of document to definition --- 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 037b202965..a3d2787cb4 100644 --- a/versions/3.0.md +++ b/versions/3.0.md @@ -67,7 +67,7 @@ An OpenAPI definition can then be used by documentation generation tools to disp ## Definitions ##### OpenAPI Document -A document (or set of documents) that define or describe an API. An OpenAPI document uses and conforms to the OpenAPI Specification. +A document (or set of documents) that defines or describes an API. An OpenAPI definition uses and conforms to the OpenAPI Specification. ##### Path Templating Path templating refers to the usage of curly braces ({}) to mark a section of a URL path as replaceable using path parameters.