Add example of using a security_scheme to the documentation (#589)

* Add example of using a security_scheme to the documentation * Update AUTHORS and add new security scheme doc example to README as well * Forgot to add all of the bits to the JSON output
marshmallow-code · Aug 18, 2020 · f075149 · f075149
1 parent 3737885
commit f075149
Show file tree

Hide file tree

Showing 3 changed files with 54 additions and 1 deletion.
diff --git a/AUTHORS.rst b/AUTHORS.rst
@@ -63,3 +63,4 @@ Contributors (chronological)
 - Ashutosh Chaudhary `@codeasashu <https://github.com/codeasashu>`_
 - Fedor Fominykh `@fedorfo <https://github.com/fedorfo>`_
 - Colin Bounouar `@Colin-b <https://github.com/Colin-b>`_
+- David Bishop `@teancom <https://github.com/teancom>`_
diff --git a/README.rst b/README.rst
@@ -67,6 +67,11 @@ Example Application
         name = fields.Str()
 
 
+    # Optional security scheme support
+    api_key_scheme = {"type": "apiKey", "in": "header", "name": "X-API-Key"}
+    spec.components.security_scheme("ApiKeyAuth", api_key_scheme)
+
+
     # Optional Flask support
     app = Flask(__name__)
 
@@ -77,6 +82,8 @@ Example Application
         ---
         get:
           description: Get a random pet
+          security:
+            - ApiKeyAuth: []
           responses:
             200:
               content:
@@ -105,6 +112,11 @@ Generated OpenAPI Spec
     #     "/random": {
     #       "get": {
     #         "description": "Get a random pet",
+    #         "security": [
+    #           {
+    #             "ApiKeyAuth": []
+    #           }
+    #         ],
     #         "responses": {
     #           "200": {
     #             "content": {
@@ -158,6 +170,13 @@ Generated OpenAPI Spec
     #           }
     #         }
     #       }
+    #       "securitySchemes": {
+    #          "ApiKeyAuth": {
+    #            "type": "apiKey",
+    #            "in": "header",
+    #            "name": "X-API-Key"
+    #         }
+    #       }
     #     }
     #   }
     # }
@@ -180,6 +199,11 @@ Generated OpenAPI Spec
     #           type: array
     #         name: {type: string}
     #       type: object
+    #   securitySchemes:
+    #     ApiKeyAuth:
+    #       in: header
+    #       name: X-API-KEY
+    #       type: apiKey
     # info: {title: Swagger Petstore, version: 1.0.0}
     # openapi: 3.0.2
     # paths:
@@ -191,6 +215,8 @@ Generated OpenAPI Spec
     #           content:
     #             application/json:
     #               schema: {$ref: '#/components/schemas/Pet'}
+    #       security:
+    #       - ApiKeyAuth: []
     # tags: []
 
 

diff --git a/docs/index.rst b/docs/index.rst
@@ -47,6 +47,11 @@ Example Application
         name = fields.Str()
 
 
+    # Optional security scheme support
+    api_key_scheme = {"type": "apiKey", "in": "header", "name": "X-API-Key"}
+    spec.components.security_scheme("ApiKeyAuth", api_key_scheme)
+
+
     # Optional Flask support
     app = Flask(__name__)
 
@@ -57,6 +62,8 @@ Example Application
         ---
         get:
           description: Get a random pet
+          security:
+            - ApiKeyAuth: []
           responses:
             200:
               description: Return a pet
@@ -121,13 +128,25 @@ Generated OpenAPI Spec
     #             "type": "string"
     #           }
     #         }
-    #       }
+    #       },
+    #     }
+    #   },
+    #   "securitySchemes": {
+    #      "ApiKeyAuth": {
+    #        "type": "apiKey",
+    #        "in": "header",
+    #        "name": "X-API-Key"
     #     }
     #   },
     #   "paths": {
     #     "/random": {
     #       "get": {
     #         "description": "Get a random pet",
+    #         "security": [
+    #           {
+    #             "ApiKeyAuth": []
+    #           }
+    #         ],
     #         "responses": {
     #           "200": {
     #             "description": "Return a pet",
@@ -171,6 +190,11 @@ Generated OpenAPI Spec
     #         name:
     #           type: string
     #       type: object
+    #   securitySchemes:
+    #     ApiKeyAuth:
+    #       in: header
+    #       name: X-API-KEY
+    #       type: apiKey
     # paths:
     #   /random:
     #     get:
@@ -182,6 +206,8 @@ Generated OpenAPI Spec
     #               schema:
     #                 $ref: '#/components/schemas/Pet'
     #           description: Return a pet
+    #       security:
+    #       - ApiKeyAuth: []
 
 User Guide
 ==========