Merge branch 'OpenAPI.next' into patch-23

RobDolinMS · web-flow · commit 4305fb8ebd10 · 2017-06-15T09:23:53.000-07:00
diff --git a/examples/v3.0/callback-example.yaml b/examples/v3.0/callback-example.yaml
@@ -0,0 +1,56 @@
+paths:
+  /streams:
+    post:
+      description: subscribes a client to receive out-of-band data
+      parameters:
+        - name: callbackUrl
+          in: query
+          required: true
+          description: |
+            the ___location where data will be sent.  Must be network accessible
+            by the source server
+          schema:
+            type: string
+            format: uri
+            example: https://tonys-server.com
+      responses:
+        '201':
+          description: subscription successfully created
+          content:
+            application/json:
+              schema:
+                description: subscription information
+                required:
+                  - subscriptionId
+                properties:
+                  subscriptionId:
+                    description: this unique identifier allows management of the subscription
+                    type: string
+                    example: 2531329f-fb09-4ef7-887e-84e648214436
+      callbacks:
+        # the name `onData` is a convenience locator
+        onData:
+          # when data is sent, it will be sent to the `callbackUrl` provided
+          # when making the subscription PLUS the suffix `/data`
+          $request.query.callbackUrl/data:
+            post:
+              requestBody:
+                description: subscription payload
+                content:
+                  application/json:
+                    schema:
+                      properties:
+                        timestamp:
+                          type: string
+                          format: date-time
+                        userData:
+                          $ref: '#/components/schemas/UserLogData'
+              responses:
+                '202':
+                  description: |
+                    Your server implementation should return this HTTP status code
+                    if the data was received successfully
+                '204':
+                  description: |
+                    Your server should return this HTTP status code if no longer interested
+                    in further updates
diff --git a/versions/3.0.md b/versions/3.0.md
@@ -102,7 +102,7 @@ For example, if a field has an array value, the JSON array representation will b
 
 ```json
 {
-   "field": [...]
+   "field": [ 1, 2, 3 ]
 }
 ```
 All field names in the specification are **case sensitive**.
@@ -632,10 +632,33 @@ The path is appended to the URL from the [`Server Object`](#serverObject) in ord
 
 Field Pattern | Type | Description
 ---|:---:|---
-<a name="pathsPath"></a>/{path} | [Path Item Object](#pathItemObject) | A relative path to an individual endpoint. The field name MUST begin with a slash. The path is **appended** (no relative URL resolution) to the expanded URL from the [`Server Object`](#serverObject)'s `url` field in order to construct the full URL. [Path templating](#pathTemplating) is allowed.
+<a name="pathsPath"></a>/{path} | [Path Item Object](#pathItemObject) | A relative path to an individual endpoint. The field name MUST begin with a slash. The path is **appended** (no relative URL resolution) to the expanded URL from the [`Server Object`](#serverObject)'s `url` field in order to construct the full URL. [Path templating](#pathTemplating) is allowed. When matching URLs, concrete (non-templated) paths would be matched before their templated counterparts. Templated paths with the same hierarchy but different templated names MUST NOT exist as they are identical. In case of ambiguous matching, it's up to the tooling to decide which one to use.
 
 This object can be extended with [Specification Extensions](#specificationExtensions). 
 
+##### Path Templating Matching
+
+Assuming the following paths, the concrete definition, `/pets/mine`, will be matched first if used:
+
+```
+  /pets/{petId}
+  /pets/mine
+```
+
+The following paths are considered identical and invalid:
+
+```
+  /pets/{petId}
+  /pets/{name}
+```
+
+The following may lead to ambiguous resolution:
+
+```
+  /{entity}/me
+  /books/{id}
+```
+
 ##### Paths Object Example
 
 ```json
@@ -1728,7 +1751,7 @@ The key value used to identify the callback object is an expression, evaluated a
 ##### Patterned Fields
 Field Pattern | Type | Description
 ---|:---:|---
-<a name="callbackExpression"></a>{expression} | [Path Item Object](#pathItemObject) | A Path Item Object used to define a callback request and expected responses.
+<a name="callbackExpression"></a>{expression} | [Path Item Object](#pathItemObject) | A Path Item Object used to define a callback request and expected responses.  A full example may be found at https://github.com/OAI/OpenAPI-Specification/blob/OpenAPI.next/examples/v3.0/callback-example.yaml
 
 This object can be extended with [Specification Extensions](#specificationExtensions). 
 
@@ -3351,7 +3374,7 @@ Field Name | Type | Validity | Description
 <a name="securitySchemeDescription"></a>description | `string` | Any | A short description for security scheme. [CommonMark syntax](http://spec.commonmark.org/) can be used for rich text representation.
 <a name="securitySchemeName"></a>name | `string` | `apiKey` | **REQUIRED**. The name of the header or query parameter to be used.
 <a name="securitySchemeIn"></a>in | `string` | `apiKey` | **REQUIRED**. The ___location of the API key. Valid values are `"query"`, `"header"` or `"cookie"`.
-<a name="securitySchemeScheme"></a>scheme | `string` | `http` | **REQUIRED**. The name of the HTTP Authorization scheme to be used in the [Authorization header as defined in RFC7235](https://tools.ietf.org/html/rfc7235#section-4.2).
+<a name="securitySchemeScheme"></a>scheme | `string` | `http` | **REQUIRED**. The name of the HTTP Authorization scheme to be used in the [Authorization header as defined in RFC7235](https://tools.ietf.org/html/rfc7235#section-5.1).
 <a name="securitySchemeBearerFormat"></a>bearerFormat | `string` | `http` (`"bearer"`) | A hint to the client to identify how the bearer token is formatted.  Bearer tokens are usually generated by an authorization server, so this information is primarily for documentation purposes.
 <a name="securitySchemeFlows"></a>flows | [OAuth Flows Object](#oauthFlowsObject) | `oauth2` | **REQUIRED**. An object containing configuration information for the flow types supported.
 <a name="securitySchemeOpenIdConnectUrl"></a>openIdConnectUrl | `string` | `openIdConnect` | **REQUIRED**. OpenId Connect URL to discover OAuth2 configuration values. This MUST be in the form of a URL.
