example as YAML/JSON via HTTP negotiation

Author: handrews

versions/3.0.4.md

@@ -3802,9 +3802,38 @@ security:
 
 See [Resolving Implicit Connections](#resolvingImplicitConnections) for more information.
 
-Entry document `openapi.yaml`:
+First, our entry document is where parsing begins. It defines the `MySecurity` security scheme to be JWT-based, and it defines on Path Item as a reference to a component in another document:
 
-```YAML
+```HTTP
+GET /api/description/openapi HTTP/1.1
+Host: www.example.com
+Accept: application/openapi+json
+```
+
+```json
+"components": {
+  "securitySchemes": {
+    "MySecurity": {
+      "type": "http",
+      "scheme": "bearer",
+      "bearerFormat": "JWT"
+    }
+  }
+},
+"paths": {
+  "/foo": {
+    "$ref": "other#/components/pathItems/Foo"
+  }
+}
+```
+
+```HTTP
+GET /api/description/openapi HTTP/1.1
+Host: www.example.com
+Accept: application/openapi+yaml
+```
+
+```yaml
 components:
   securitySchemes:
     MySecurity:
@@ -3813,12 +3842,44 @@ components:
       bearerFormat: JWT
 paths:
   /foo:
-    $ref: "other.yaml#/components/pathItems/Foo"
+    $ref: "other#/components/pathItems/Foo"
 ```
 
-Referenced document `other.yaml`:
+Next, we have our referenced document, `other`, that we presumably request in the same format we requested for the entry document.  But the fact that we don't use file extensions gives the client the flexibilty to choose on a resource-by-resource basis, assuming both representations are available:
 
-```YAML
+```HTTP
+GET /api/description/other HTTP/1.1
+Host: www.example.com
+Accept: application/openapi+json
+```
+
+```json
+"components": {
+  "securitySchemes": {
+    "MySecurity": {
+      "type": "http",
+      "scheme": "basic"
+    }
+  },
+  "pathItems": {
+    "Foo": {
+      "get": {
+        "security": [
+         "MySecurity": []
+        ]
+      }
+    }
+  }
+}
+```
+
+```HTTP
+GET /api/description/other HTTP/1.1
+Host: www.example.com
+Accept: application/openapi+yaml
+```
+
+```yaml
 components:
   securitySchemes:
     MySecurity:
@@ -3831,7 +3892,7 @@ components:
         - MySecurity: []
 ```
 
-In this example, it is implementation-defined whether the Security Requirement for "MySecurity" in `other.yaml` resolves to `other.yaml#/components/securitySchemes/MySecurity` or the RECOMMENDED resolved location of `openapi.yaml#/components/securitySchemes/MySecurity`.
+In this `other` document, the reference path item has a Security Requirement for the Security Scheme "MySecurity".  But there is a Security Scheme by that name in the `other` document as well.  As discussed in [Resolving Implicit Connections](#resolvingImplicitConnections), which "MySecurity" gets used is [implementation-defined](#undefinedAndImplementationDefinedBehavior).  However, as also documented in that section, it is RECOMMENDED that tools resolve component names from the [entry document](#documentStructure).  As with all implementation-defined behavior, it is important to check tool documentation to determine which behavior is supported.
 
 ### <a name="specificationExtensions"></a>Specification Extensions