Add description for securityDefinitions

demo/swagger.yaml

@@ -26,6 +26,14 @@ info:
     This API features Cross-Origin Resource Sharing (CORS) implemented in compliance with  [W3C spec](https://www.w3.org/TR/cors/).
     And that allows cross-domain communication from the browser.
     All responses have a wildcard same-origin which makes them completely public and accessible to everyone, including any code on any site.
+    # Authentication
+    Petstore offers two forms of authentication:
+      - API Key
+      - OAuth2
+
+    OAuth2 - an open protocol to allow secure authorization in a simple
+    and standard method from web, mobile and desktop applications.
+    <!-- ReDoc-Inject: <security-definitions> -->
   version: 1.0.0
   title: Swagger Petstore
   termsOfService: 'http://swagger.io/terms/'
@@ -48,6 +56,9 @@ tags:
     description: Operations about user
 securityDefinitions:
   petstore_auth:
+    description: |
+      Get access to data while protecting your account credentials.
+      OAuth2 is also a safer and more secure way to give you access.
     type: oauth2
     authorizationUrl: 'http://petstore.swagger.io/api/oauth/dialog'
     flow: implicit
@@ -55,6 +66,8 @@ securityDefinitions:
       'write:pets': modify pets in your account
       'read:pets': read your pets
   api_key:
+    description: |
+      For this sample, you can use the api key `special-key` to test the authorization filters.
     type: apiKey
     name: api_key
     in: header