Merge branch 'OpenAPI.next' into earth2marsh-patch-1

earth2marsh · web-flow · commit 42da4a4479c7 · 2017-02-27T21:45:20.000-08:00
diff --git a/versions/3.0.md b/versions/3.0.md
@@ -12,7 +12,7 @@ The OpenAPI Specification (OAS) is a project used to describe and document RESTf
 
 
 The OpenAPI 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 programming languages.
+These files can then be used by documentation generation tools to display the API and code generation tools to generate clients in various programming languages.
 
 Additional utilities can also take advantage of the resulting files, such as testing tools.
 
@@ -33,39 +33,39 @@ Additional utilities can also take advantage of the resulting files, such as tes
 		- [Info Object](#infoObject)
 			- [Contact Object](#contactObject)
 			- [License Object](#licenseObject)
-		- [Server Object](#server-object)
-		- [Components Object](#components-object)
-		- [Paths Object](#paths-object)
-		- [Path Item Object](#path-item-object)
-		- [Operation Object](#operation-object)
-		- [External Documentation Object](#external-documentation-object)
-		- [Parameter Object](#parameter-object)
-		- [Request Body Object](#request-body-object)
-		- [Content Object](#content-object)
-		- [Content Type Object](#content-type-object)
-		- [Responses Object](#responses-object)
-		- [Response Object](#response-object)
-		- [Headers Object](#headers-object)
-		- [Examples Object](#examples-object)
-		- [Links Object](#links-object)
-		- [Link Object](#link-object)
-		- [Variable substitution](#variable-substitution)
-		- [Link Parameters](#link-parameters)
-		- [Header Object](#header-object)
-		- [Tag Object](#tag-object)
-		- [Examples Object](#examples-object)
-		- [Reference Object](#reference-object)
-		- [Schema Object](#schema-object)
-		- [XML Object](#xml-object)
-		- [Definitions Object](#definitions-object)
-		- [Parameters Definitions Object](#parameters-definitions-object)
-		- [Responses Definitions Object](#responses-definitions-object)
-		- [Security Definitions Object](#security-definitions-object)
-		- [Security Scheme Object](#security-scheme-object)
-		- [Scopes Object](#scopes-object)
-		- [Security Requirement Object](#security-requirement-object)
-	- [Specification Extensions](#specification-extensions)
-	- [Security Filtering](#security-filtering)
+		- [Server Object](#serverObject)
+		- [Components Object](#componentsObject)
+		- [Paths Object](#pathsObject)
+		- [Path Item Object](#pathItemObject)
+		- [Operation Object](#operationObject)
+		- [External Documentation Object](#externalDocumentationObject)
+		- [Parameter Object](#parameterObject)
+		- [Request Body Object](#requestBodyObject)
+		- [Content Object](#contentObject)
+		- [Content Type Object](#contentTypeObject)
+		- [Responses Object](#responsesObject)
+		- [Response Object](#responseObject)
+		- [Headers Object](#headersObject)
+		- [Examples Object](#examplesObject)
+		- [Links Object](#linksObject)
+		- [Link Object](#linkObject)
+		- [Variable substitution](#variableSubstitution)
+		- [Link Parameters](#linkParameters)
+		- [Header Object](#headerObject)
+		- [Tag Object](#tagObject)
+		- [Examples Object](#examplesObject)
+		- [Reference Object](#referenceObject)
+		- [Schema Object](#schemaObject)
+		- [XML Object](#xmlObject)
+		- [Definitions Object](#definitionsObject)
+		- [Parameters Definitions Object](#parametersDefinitionsObject)
+		- [Responses Definitions Object](#responsesDefinitionsObject)
+		- [Security Definitions Object](#securityDefinitionsObject)
+		- [Security Scheme Object](#securitySchemeObject)
+		- [Scopes Object](#scopesObject)
+		- [Security Requirement Object](#securityRequirementObject)
+	- [Specification Extensions](#specificationExtensions)
+	- [Security Filtering](#securityFiltering)
 - [Appendix A: Revision History](#revisionHistory)
 	
 
@@ -94,7 +94,8 @@ Some examples of possible media type definitions:
   application/vnd.github.v3.patch
 ```
 ##### <a name="httpCodes"></a>HTTP Status Codes
-The HTTP Status Codes are used to indicate the status of the executed operation. The available status codes are initially defined by [RFC 7231](http://tools.ietf.org/html/rfc7231#section-6) and registered status codes are listed in the [IANA Status Code Registry](http://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml).
+The HTTP Status Codes are used to indicate the status of the executed operation. 
+The available status codes are defined by [RFC 7231](http://tools.ietf.org/html/rfc7231#section-6) and registered status codes are listed in the [IANA Status Code Registry](http://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml).
 
 ## Specification
 
@@ -134,10 +135,12 @@ By convention, it is RECOMMENDED that the OpenAPI Specification (OAS) file be na
 
 ### <a name="dataTypes"></a>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 value.
+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 value.
 Models are described using the [Schema Object](#schemaObject) which is an extended subset of JSON Schema Specification Wright Draft 00.
 
-<a name="dataTypeFormat"></a>Primitives have an optional modifier property `format`.
+<a name="dataTypeFormat"></a>Primitives have an optional modifier property: `format`.
 OAS uses several known formats to more finely define the data type being used.
 However, the `format` property is an open `string`-valued property, and can have any value to support documentation needs.
 Formats such as `"email"`, `"uuid"`, etc., can be used even though they are not defined by this specification.
@@ -203,7 +206,7 @@ In subsequent versions of the OpenAPI Specification, care will be given such tha
 #### <a name="infoObject"></a>Info Object
 
 The object provides metadata about the API.
-The metadata can be used by the clients if needed, and can be presented in the Swagger-UI for convenience.
+The metadata can be used by the clients if needed, and can be presented in editing or documentation generation tools for convenience.
 
 ##### Fixed Fields
 
@@ -214,21 +217,22 @@ 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).  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.
+<a name="infoVersion"></a>version | `string` | **Required.** The version of the API definition (which is distinct from the OpenAPI specification version or the API implementation version).
+
 
 This object can be extended with [Specification Extensions](#specificationExtensions). 
 
 ##### Info Object Example:
 
 ```json
 {
-  "title": "Swagger Sample App",
+  "title": "Sample Pet Store App",
   "description": "This is a sample server for a pet store.",
-  "termsOfService": "http://swagger.io/terms/",
+  "termsOfService": "http://example.com/terms/",
   "contact": {
     "name": "API Support",
-    "url": "http://www.swagger.io/support",
-    "email": "support@swagger.io"
+    "url": "http://www.example.com/support",
+    "email": "support@example.com"
   },
   "license": {
     "name": "Apache 2.0",
@@ -239,13 +243,13 @@ This object can be extended with [Specification Extensions](#specificationExtens
 ```
 
 ```yaml
-title: Swagger Sample App
+title: Sample Pet Store App
 description: This is a sample server for a pet store.
-termsOfService: http://swagger.io/terms/
+termsOfService: http://example.com/terms/
 contact:
   name: API Support
-  url: http://www.swagger.io/support
-  email: support@swagger.io
+  url: http://www.example.com/support
+  email: support@example.com
 license:
   name: Apache 2.0
   url: http://www.apache.org/licenses/LICENSE-2.0.html
@@ -271,15 +275,15 @@ This object can be extended with [Specification Extensions](#specificationExtens
 ```json
 {
   "name": "API Support",
-  "url": "http://www.swagger.io/support",
-  "email": "support@swagger.io"
+  "url": "http://www.example.com/support",
+  "email": "support@example.com"
 }
 ```
 
 ```yaml
 name: API Support
-url: http://www.swagger.io/support
-email: support@swagger.io
+url: http://www.example.com/support
+email: support@example.com
 ```
 
 #### <a name="licenseObject"></a>License Object
@@ -575,7 +579,7 @@ Describes a single API operation on a path.
 Field Name | Type | Description
 ---|:---:|---
 <a name="operationTags"></a>tags | [`string`] | A list of tags for API documentation control. Tags can be used for logical grouping of operations by resources or any other qualifier.
-<a name="operationSummary"></a>summary | `string` | A short summary of what the operation does. For maximum readability in the swagger-ui, this field SHOULD be less than 120 characters.
+<a name="operationSummary"></a>summary | `string` | A short summary of what the operation does. For maximum readability in editing or documentation generation tools, this field SHOULD be less than 120 characters.
 <a name="operationDescription"></a>description | `string` | A verbose explanation of the operation behavior. [CommonMark syntax](http://spec.commonmark.org/) can be used for rich text representation.
 <a name="operationExternalDocs"></a>externalDocs | [External Documentation Object](#externalDocumentationObject) | Additional external documentation for this operation.
 <a name="operationId"></a>operationId | `string` | Unique string used to identify the operation. The id MUST be unique among all operations described in the API. Tools and libraries MAY use the operationId to uniquely identify an operation, therefore, it is recommended to follow common programming naming conventions.
@@ -597,7 +601,6 @@ This object can be extended with [Specification Extensions](#specificationExtens
     "pet"
   ],
   "summary": "Updates a pet in the store with form data",
-  "description": "",
   "operationId": "updatePetWithForm",
   "parameters": [
     {
@@ -659,7 +662,6 @@ This object can be extended with [Specification Extensions](#specificationExtens
 tags:
 - pet
 summary: Updates a pet in the store with form data
-description: ''
 operationId: updatePetWithForm
 parameters:
 - name: petId
@@ -716,13 +718,13 @@ This object can be extended with [Specification Extensions](#specificationExtens
 ```json
 {
   "description": "Find more info here",
-  "url": "https://swagger.io"
+  "url": "https://example.com"
 }
 ```
 
 ```yaml
 description: Find more info here
-url: https://swagger.io
+url: https://example.com
 ```
 
 #### <a name="parameterObject"></a>Parameter Object
@@ -1088,6 +1090,7 @@ Field Name | Type | Description
 <a name="contentTypeSchema"></a>schema | [Schema Object](#schemaObject) | The schema defining the type used for the request body.
 <a name="contentTypeExamples"></a>examples | [Examples Array](#examplesArray) | Examples of the content type.  Each example in the Examples array SHOULD be in the correct format as specified in the _content_ type.  The `examples` object is mutually exclusive to the `example` object.  Furthermore, if referencing a `schema` which contains an example, the `examples` value SHALL _override_ the example provided by the schema.
 <a name="contentTypeExample"></a>example | [Example Object](#exampleObject) | Example of the content type.  The example object SHOULD be in the correct format as specified in the _content_ type.  The `example` object is mutually exclusive to the `examples` object.  Furthermore, if referencing a `schema` which contains an example, the `example` value SHALL _override_ the the example provided by the schema.
+<a name="contentTypeEncoding"></a>encoding | [Encoding Object](#encodingObject) | Encoding of the content type.  The encoding object SHOULD only apply to `requestBody` objects when the content type is `multipart`.
 
 ##### Patterned Fields
 Field Pattern | Type | Description
@@ -1291,13 +1294,13 @@ requestBody:
             # default is application/octet-stream, need to declare an image type only!
             type: string
             format: binary
-encoding:
-  historyMetadata:
-    # require XML content-type in utf-8 encoding
-    contentType: application/xml; charset=utf-8
-  profileImage:
-    # only accept png/jpeg
-    contentType: image/png, image/jpeg
+      encoding:
+        historyMetadata:
+          # require XML content-type in utf-8 encoding
+          contentType: application/xml; charset=utf-8
+        profileImage:
+          # only accept png/jpeg
+          contentType: image/png, image/jpeg
 ```
 
 #### <a name="responsesObject"></a>Responses Object
@@ -2824,7 +2827,7 @@ In this example, a full model definition is shown.
       "name": {
         "type": "string",
         "xml": {
-          "namespace": "http://swagger.io/schema/sample",
+          "namespace": "http://example.com/schema/sample",
           "prefix": "sample"
         }
       }
@@ -2845,13 +2848,13 @@ Person:
     name:
       type: string
       xml:
-        namespace: http://swagger.io/schema/sample
+        namespace: http://example.com/schema/sample
         prefix: sample
 ```
 
 ```xml
 <Person id="123">
-    <sample:name xmlns:sample="http://swagger.io/schema/sample">example</sample:name>
+    <sample:name xmlns:sample="http://example.com/schema/sample">example</sample:name>
 </Person>
 ```
 
@@ -3256,7 +3259,7 @@ Field Pattern | Type | Description
     "type": "oauth2",
     "flow": {
       "implicit": {
-        "authorizationUrl": "http://swagger.io/api/oauth/dialog",
+        "authorizationUrl": "http://example.com/api/oauth/dialog",
         "scopes": {
           "write:pets": "modify pets in your account",
           "read:pets": "read your pets"
@@ -3276,7 +3279,7 @@ petstore_auth:
   type: oauth2
   flow: 
     implicit:
-      authorizationUrl: http://swagger.io/api/oauth/dialog
+      authorizationUrl: http://example.com/api/oauth/dialog
       scopes:
         write:pets: modify pets in your account
         read:pets: read your pets
@@ -3356,7 +3359,7 @@ bearerFormat: JWT
   "type": "oauth2",
   "flow": {
     "implicit": {
-      "authorizationUrl": "https://swagger.io/api/oauth/dialog",
+      "authorizationUrl": "https://example.com/api/oauth/dialog",
       "scopes": {
         "write:pets": "modify pets in your account",
         "read:pets": "read your pets"
@@ -3370,7 +3373,7 @@ bearerFormat: JWT
 type: oauth2
 flow: 
   implicit:
-    authorizationUrl: https://swagger.io/api/oauth/dialog
+    authorizationUrl: https://example.com/api/oauth/dialog
     scopes:
       write:pets: modify pets in your account
       read:pets: read your pets
@@ -3411,15 +3414,15 @@ This object can be extended with [Specification Extensions](#specificationExtens
   "type": "oauth2",
   "flow": {
     "implicit": {
-      "authorizationUrl": "https://swagger.io/api/oauth/dialog",
+      "authorizationUrl": "https://example.com/api/oauth/dialog",
       "scopes": {
         "write:pets": "modify pets in your account",
         "read:pets": "read your pets"
       }
     },
     "authorizationCode": {
-      "authorizationUrl": "https://swagger.io/api/oauth/dialog",
-      "tokenUrl": "https://swagger.io/api/oauth/token",
+      "authorizationUrl": "https://example.com/api/oauth/dialog",
+      "tokenUrl": "https://example.com/api/oauth/token",
       "scopes": {
         "write:pets": "modify pets in your account",
         "read:pets": "read your pets"
@@ -3433,13 +3436,13 @@ This object can be extended with [Specification Extensions](#specificationExtens
 type: oauth2
 flow: 
   implicit:
-    authorizationUrl: https://swagger.io/api/oauth/dialog
+    authorizationUrl: https://example.com/api/oauth/dialog
     scopes:
       write:pets: modify pets in your account
       read:pets: read your pets
   authorizationCode:
-    authorizationUrl: https://swagger.io/api/oauth/dialog
-    tokenUrl: https://swagger.io/api/oauth/token
+    authorizationUrl: https://example.com/api/oauth/dialog
+    tokenUrl: https://example.com/api/oauth/token
     scopes:
       write:pets: modify pets in your account
       read:pets: read your pets 
