Merge remote-tracking branch 'refs/remotes/origin/OpenAPI.next' into dm/components

# Conflicts:
#	versions/3.0.md

Author: darrelmiller

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.
 
@@ -131,10 +131,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.
@@ -200,7 +202,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
 
@@ -220,13 +222,13 @@ This object can be extended with [Specification Extensions](#specificationExtens
 
 ```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",
@@ -237,13 +239,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
@@ -269,15 +271,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
@@ -489,7 +491,7 @@ my\org\User
       "type": "oauth2",
       "flow": {
         "implicit": {
-          "authorizationUrl": "http://swagger.io/api/oauth/dialog",
+          "authorizationUrl": "http://example.org/api/oauth/dialog",
           "scopes": {
             "write:pets": "modify pets in your account",
             "read:pets": "read your pets"
@@ -555,7 +557,7 @@ components:
       type: oauth2
       flow: 
         implicit:
-          authorizationUrl: http://swagger.io/api/oauth/dialog
+          authorizationUrl: http://example.org/api/oauth/dialog
           scopes:
             write:pets: modify pets in your account
             read:pets: read your pets
@@ -735,7 +737,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.
@@ -757,7 +759,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": [
     {
@@ -819,7 +820,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
@@ -876,13 +876,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
@@ -2997,7 +2997,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"
         }
       }
@@ -3018,13 +3018,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>
 ```
 
@@ -3311,7 +3311,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"
@@ -3325,7 +3325,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
@@ -3366,15 +3366,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"
@@ -3388,13 +3388,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