Add example resolution of Security Requirement (3.2.0 port of 3856 3/4)

Includes examples as either YAML or JSON via HTTP negotiation

Author: handrews

versions/3.2.0.md

@@ -239,6 +239,9 @@ The interface approach can also work for Discriminator Objects and Schema Object
 There are no URI-based alternatives for the Security Requirement Object or for the Operation Object's `tags` field.
 These limitations are expected to be addressed in a future release.
 
+See [Security Requirement in a Referenced Document](#security-requirement-in-a-referenced-document) for an example of the possible resolutions, including which one is recommended by this section.
+The behavior for Discrimator Object non-URI mappings and for the Operation Object's `tags` field operate on the same principles.
+
 Note that no aspect of implicit connection resolution changes how [URIs are resolved](#relativeReferencesURI), or restricts their possible targets.
 
 ### <a name="dataTypes"></a>Data Types
@@ -4035,6 +4038,102 @@ security:
     - read:pets
 ```
 
+###### Security Requirement in a Referenced Document
+
+See [Resolving Implicit Connections](#resolvingImplicitConnections) for more information.
+
+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:
+
+```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:
+      type: http
+      scheme: bearer
+      bearerFormat: JWT
+paths:
+  /foo:
+    $ref: "other#/components/pathItems/Foo"
+```
+
+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:
+
+```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:
+      type: http
+      scheme: basic
+  pathItems:
+    Foo:
+      get:
+        security:
+        - 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
 
 While the OpenAPI Specification tries to accommodate most use cases, additional data can be added to extend the specification at certain points.