Merge pull request #4091 from handrews/sec-req-311

3.1.1 port of Move complex Sec Req example to appendix F

Author: lornajane

Diff for: versions/3.1.1.md

@@ -198,7 +198,7 @@ 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.
+See [Appendix F: Resolving Security Requirements in a Referenced Document](#appendix-f-resolving-security-requirements-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](#relative-references-in-api-description-uris), or restricts their possible targets.
@@ -3939,6 +3939,8 @@ When a list of Security Requirement Objects is defined on the [OpenAPI Object](#
 
 ##### Security Requirement Object Examples
 
+See also [Appendix F: Resolving Security Requirements in a Referenced Document](#appendix-f-resolving-security-requirements-in-a-referenced-document) for an example using Security Requirement Objects in multi-document OpenAPI Descriptions.
+
 ###### Non-OAuth2 Security Requirement
 
 ```json
@@ -3988,102 +3990,6 @@ security:
       - read:pets
 ```
 
-###### Security Requirement in a Referenced Document
-
-See [Resolving Implicit Connections](#resolving-implicit-connections) for more information.
-
-First, the [entry document](#openapi-description-structure) is where parsing begins. It defines the `MySecurity` security scheme to be JWT-based, and it defines a 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'
-```
-
-This entry document references another document, `other`, without using a file extension.  This gives the client the flexibility to choose an acceptable format 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 the `other` document, the referenced path item has a Security Requirement for a Security Scheme, `MySecurity`. The same Security Scheme exists in the original entry document. As outlined in [Resolving Implicit Connections](#resolving-implicit-connections), `MySecurity` is resolved with an [implementation-defined behavior](#undefined-and-implementation-defined-behavior). However, documented in that section, it is RECOMMENDED that tools resolve component names from the [entry document](#openapi-description-structure). As with all implementation-defined behavior, it is important to check tool documentation to determine which behavior is supported.
-
 ### Specification Extensions
 
 While the OpenAPI Specification tries to accommodate most use cases, additional data can be added to extend the specification at certain points.
@@ -4556,3 +4462,99 @@ Code that relies on leaving these delimiters unencoded, while using regular perc
 For maximum interoperability, it is RECOMMENDED to either define and document an additional escape convention while percent-encoding the delimiters for these styles, or to avoid these styles entirely.
 The exact method of additional encoding/escaping is left to the API designer, and is expected to be performed before serialization and encoding described in this specification, and reversed after this specification's encoding and serialization steps are reversed.
 This keeps it outside of the processes governed by this specification.
+
+## Appendix F: Resolving Security Requirements in a Referenced Document
+
+This appendix shows how to retrieve an HTTP-accessible multi-document OpenAPI Description (OAD) and resolve a [Security Requirement Object](#security-requirement-object) in the referenced (non-entry) document.  See [Resolving Implicit Connections](#resolving-implicit-connections) for more information.
+
+First, the [entry document](#openapi-description-structure) is where parsing begins. It defines the `MySecurity` security scheme to be JWT-based, and it defines a 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'
+```
+
+This entry document references another document, `other`, without using a file extension.  This gives the client the flexibility to choose an acceptable format 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 the `other` document, the referenced path item has a Security Requirement for a Security Scheme, `MySecurity`. The same Security Scheme exists in the original entry document. As outlined in [Resolving Implicit Connections](#resolving-implicit-connections), `MySecurity` is resolved with an [implementation-defined behavior](#undefined-and-implementation-defined-behavior). However, documented in that section, it is RECOMMENDED that tools resolve component names from the [entry document](#openapi-description-structure). As with all implementation-defined behavior, it is important to check tool documentation to determine which behavior is supported.