Merge pull request #8064 from magento/db_swagger_docs

Adds information about securing the Swagger endpoint

Author: dobooth

src/guides/v2.3/rest/generate-local.md

@@ -21,9 +21,9 @@ To view the Swagger documentation for a specific store view, use this URL:
 
  The value of `store_code` must be one of the following:
 
-*  `default`
-*  The assigned store code
-*  `all`. This value only applies to the [CMS](https://glossary.magento.com/cms) and Product modules. If this value is specified, the API call affects all the merchant's stores.
+-  `default`
+-  The assigned store code
+-  `all`. This value only applies to the [CMS](https://glossary.magento.com/cms) and Product modules. If this value is specified, the API call affects all the merchant's stores.
 
 By default, Magento returns documentation for resources available to anonymous users across all stores. If you specify a valid value in the `api_key` text box in the upper right corner, Swagger returns documentation for all the endpoints the user has access to. To generate an API key, call the `POST /V1/integration/customer/token` or `POST /V1/integration/admin/token` as directed in [Token-based authentication]({{ page.baseurl }}/get-started/authentication/gs-authentication-token.html).
 
@@ -63,7 +63,25 @@ To return the complete JSON schema, specify the `?services=all` parameter in the
 
 The base URL for returning the asynchronous schema is `http://<magento_host>/rest/<store_code>/async/schema`.
 
+## Security
+
+By default, the `/swagger` endpoint is open on Magento instances. Leaving it open on a public instance could potentially expose system information that should not be readable.
+
+To close off the `/swagger` endpoint, disable the following modules:
+
+-  Swagger
+-  SwaggerWebapi
+-  SwaggerWebapiAsync
+
+To ensure proper functionality, always test Magento instances after disabling modules.
+
+You may also use web server rewrite rules to redirect users trying to access the endpoint:
+
+-  [nginx rewrite module](http://nginx.org/en/docs/http/ngx_http_rewrite_module.html#rewrite)
+-  [apache mod_rewrite](https://httpd.apache.org/docs/2.4/rewrite/)
+
 {:.ref-header}
 Related topics
 
+[Restricting access to anonymous web APIs]({{ page.baseurl }}/rest/anonymous-api-security.html)
 [Token-based authentication]({{ page.baseurl }}/get-started/authentication/gs-authentication-token.html)

src/guides/v2.4/rest/generate-local.md

@@ -21,9 +21,9 @@ To view the Swagger documentation for a specific store view, use this URL:
 
  The value of `store_code` must be one of the following:
 
-*  `default`
-*  The assigned store code
-*  `all`. This value only applies to the [CMS](https://glossary.magento.com/cms) and Product modules. If this value is specified, the API call affects all the merchant's stores.
+-  `default`
+-  The assigned store code
+-  `all`. This value only applies to the [CMS](https://glossary.magento.com/cms) and Product modules. If this value is specified, the API call affects all the merchant's stores.
 
 By default, Magento returns documentation for resources available to anonymous users across all stores. If you specify a valid customer or admin token in the `api_key` text box in the upper right corner, Swagger returns documentation for all the endpoints the user has access to. To generate an API key, call the `POST /V1/integration/customer/token` endpoint or a 2FA endpoint such as `POST /V1/tfa/provider/google/authenticate` with the appropriate payload, as directed in [Token-based authentication]({{ page.baseurl }}/get-started/authentication/gs-authentication-token.html).
 
@@ -60,7 +60,25 @@ To return the complete JSON schema, specify the `?services=all` parameter in the
 
 The base URL for returning the asynchronous schema is `http://<magento_host>/rest/<store_code>/async/schema`.
 
+## Security
+
+By default, the `/swagger` endpoint is open on Magento instances. Leaving it open on a public instance could potentially expose system information that should not be readable.
+
+To close off the `/swagger` endpoint, disable the following modules:
+
+-  Swagger
+-  SwaggerWebapi
+-  SwaggerWebapiAsync
+
+To ensure proper functionality, always test Magento instances after disabling modules.
+
+You may also use web server rewrite rules to redirect users trying to access the endpoint:
+
+-  [nginx rewrite module](http://nginx.org/en/docs/http/ngx_http_rewrite_module.html#rewrite)
+-  [apache mod_rewrite](https://httpd.apache.org/docs/2.4/rewrite/)
+
 {:.ref-header}
 Related topics
 
+[Restricting access to anonymous web APIs]({{ page.baseurl }}/rest/anonymous-api-security.html)
 [Token-based authentication]({{ page.baseurl }}/get-started/authentication/gs-authentication-token.html)