Add section on adding top-level components objects

Adapted from #222 (comment)

Author: sloria

docs/special_topics.rst

@@ -43,3 +43,58 @@ JSON
     import json
 
     json.dumps(spec.to_dict())
+
+Documenting Top-level Components
+--------------------------------
+
+To add objects within the top-level ``components`` object, pass the
+components to the ``APISpec`` as a keyword argument.
+
+Here is an example that includes a `Security Scheme Object <https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.1.md#securitySchemeObject>`_.
+
+.. code-block:: python
+
+    import yaml
+    from apispec import APISpec
+    from apispec.utils import validate_swagger
+
+    OPENAPI_SPEC = """
+    openapi: 3.0.1
+    info:
+      description: Server API document
+      title: Server API
+      version: 1.0.0
+    servers:
+    - url: http://localhost:{port}/
+      description: The development API server
+      variables:
+        port:
+          enum:
+          - '3000'
+          - '8888'
+          default: '3000'
+    components:
+      securitySchemes:
+        bearerAuth:
+          type: http
+          scheme: bearer
+          bearerFormat: JWT
+    """
+
+    settings = yaml.load(OPENAPI_SPEC)
+    # retrieve  title, version, and openapi version
+    title = settings['info'].pop('title')
+    spec_version = settings['info'].pop('version')
+    openapi_version = settings.pop('openapi')
+
+    spec = APISpec(
+        title=title,
+        version=spec_version,
+        openapi_version=openapi_version,
+        plugins=(
+            'apispec.ext.marshmallow',
+        ),
+        **settings
+    )
+
+    validate_swagger(spec)