diff --git a/README.md b/README.md
index e74445c4..d5248019 100644
--- a/README.md
+++ b/README.md
@@ -112,35 +112,6 @@ To use swagger-ui's bundles, you should take a look at the [source of swagger-ui
     })
 ```
 
-#### OAuth2 configuration
-You can configure OAuth2 authorization by calling `initOAuth` method with passed configs under the instance of `SwaggerUIBundle`
-default `client_id` and `client_secret`, `realm`, an application name `appName`, `scopeSeparator`, `additionalQueryStringParams`,
-`useBasicAuthenticationWithAccessCodeGrant`.
-
-Config Name | Description
---- | ---
-client_id | Default clientId. MUST be a string
-client_secret | Default clientSecret. MUST be a string
-realm | realm query parameter (for oauth1) added to `authorizationUrl` and `tokenUrl` . MUST be a string
-appName | application name, displayed in authorization popup. MUST be a string
-scopeSeparator | scope separator for passing scopes, encoded before calling, default value is a space (encoded value `%20`). MUST be a string
-additionalQueryStringParams | Additional query parameters added to `authorizationUrl` and `tokenUrl`. MUST be an object
-useBasicAuthenticationWithAccessCodeGrant | Only activated for the `accessCode` flow.  During the `authorization_code` request to the `tokenUrl`, pass the [Client Password](https://tools.ietf.org/html/rfc6749#section-2.3.1) using the HTTP Basic Authentication scheme (`Authorization` header with `Basic base64encoded[client_id:client_secret]`).  The default is `false`
-
-```javascript
-const ui = SwaggerUIBundle({...})
-
-// Method can be called in any place after calling constructor SwaggerUIBundle
-ui.initOAuth({
-    clientId: "your-client-id",
-    clientSecret: "your-client-secret-if-required",
-    realm: "your-realms",
-    appName: "your-app-name",
-    scopeSeparator: " ",
-    additionalQueryStringParams: {test: "hello"}
-  })
-```
-
 If you'd like to use the bundle files via npm, check out the [`swagger-ui-dist` package](https://www.npmjs.com/package/swagger-ui-dist).
 
 ### Plugins
diff --git a/docs/usage/cors.md b/docs/usage/cors.md
index f2d39709..3b12273e 100644
--- a/docs/usage/cors.md
+++ b/docs/usage/cors.md
@@ -1,4 +1,4 @@
-## CORS Support
+# CORS
 
 CORS is a technique to prevent websites from doing bad things with your personal data.  Most browsers + JavaScript toolkits not only support CORS but enforce it, which has implications for your API server which supports Swagger.
 
diff --git a/docs/usage/oauth2.md b/docs/usage/oauth2.md
new file mode 100644
index 00000000..3071b29f
--- /dev/null
+++ b/docs/usage/oauth2.md
@@ -0,0 +1,28 @@
+# OAuth2 configuration
+You can configure OAuth2 authorization by calling `initOAuth` method with passed configs under the instance of `SwaggerUIBundle`
+default `client_id` and `client_secret`, `realm`, an application name `appName`, `scopeSeparator`, `additionalQueryStringParams`,
+`useBasicAuthenticationWithAccessCodeGrant`.
+
+Config Name | Description
+--- | ---
+client_id | Default clientId. MUST be a string
+client_secret | Default clientSecret. MUST be a string
+realm | realm query parameter (for oauth1) added to `authorizationUrl` and `tokenUrl` . MUST be a string
+appName | application name, displayed in authorization popup. MUST be a string
+scopeSeparator | scope separator for passing scopes, encoded before calling, default value is a space (encoded value `%20`). MUST be a string
+additionalQueryStringParams | Additional query parameters added to `authorizationUrl` and `tokenUrl`. MUST be an object
+useBasicAuthenticationWithAccessCodeGrant | Only activated for the `accessCode` flow.  During the `authorization_code` request to the `tokenUrl`, pass the [Client Password](https://tools.ietf.org/html/rfc6749#section-2.3.1) using the HTTP Basic Authentication scheme (`Authorization` header with `Basic base64encoded[client_id:client_secret]`).  The default is `false`
+
+```javascript
+const ui = SwaggerUIBundle({...})
+
+// Method can be called in any place after calling constructor SwaggerUIBundle
+ui.initOAuth({
+    clientId: "your-client-id",
+    clientSecret: "your-client-secret-if-required",
+    realm: "your-realms",
+    appName: "your-app-name",
+    scopeSeparator: " ",
+    additionalQueryStringParams: {test: "hello"}
+  })
+```