From 30ac4d18f70d3901dba9476e1cfaa2654e052eca Mon Sep 17 00:00:00 2001
From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com>
Date: Tue, 21 Jul 2026 03:50:31 +0000
Subject: [PATCH 1/5] docs: note that securityScheme description overrides the
auto-generated Authorization field text
---
api-playground/openapi-setup.mdx | 19 +++++++++++++++++++
1 file changed, 19 insertions(+)
diff --git a/api-playground/openapi-setup.mdx b/api-playground/openapi-setup.mdx
index d7dd0d5486..de1506bdbc 100644
--- a/api-playground/openapi-setup.mdx
+++ b/api-playground/openapi-setup.mdx
@@ -151,6 +151,25 @@ The `x-default` extension supports `apiKey` and `http` bearer security scheme ty
Use `x-default` on other schema properties in your OpenAPI specification to set a default value in the API playground without affecting the `default` field in the schema definition. Unlike security schemes, prefill for non-security-scheme properties only takes effect when you set [`api.examples.prefill`](/organize/settings-api) to `true` in your [`docs.json`](/api-playground/overview#example-configuration).
+#### Customize the authorization field description
+
+When you configure a security scheme, Mintlify auto-generates a description for the `Authorization` field in the API playground. Override this text by adding a `description` field to the security scheme in your OpenAPI specification.
+
+```json {6}
+{
+ "components": {
+ "securitySchemes": {
+ "bearerAuth": {
+ "type": "http",
+ "scheme": "bearer",
+ "description": "Your API key from the [dashboard](https://example.com/dashboard). Prefix with `Bearer ` when sending the header."
+ }
+ }
+ }
+}
+```
+
+The `description` field supports Markdown and appears in place of the auto-generated text on every endpoint that uses the security scheme.
## Let visitors download your spec
From ad2353dc64368a61fb8d691c984796749f8f06cc Mon Sep 17 00:00:00 2001
From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com>
Date: Tue, 21 Jul 2026 05:33:01 +0000
Subject: [PATCH 2/5] docs: remove authorization description subsection from
openapi setup page
---
api-playground/openapi-setup.mdx | 20 --------------------
1 file changed, 20 deletions(-)
diff --git a/api-playground/openapi-setup.mdx b/api-playground/openapi-setup.mdx
index de1506bdbc..e371841bc4 100644
--- a/api-playground/openapi-setup.mdx
+++ b/api-playground/openapi-setup.mdx
@@ -151,26 +151,6 @@ The `x-default` extension supports `apiKey` and `http` bearer security scheme ty
Use `x-default` on other schema properties in your OpenAPI specification to set a default value in the API playground without affecting the `default` field in the schema definition. Unlike security schemes, prefill for non-security-scheme properties only takes effect when you set [`api.examples.prefill`](/organize/settings-api) to `true` in your [`docs.json`](/api-playground/overview#example-configuration).
-#### Customize the authorization field description
-
-When you configure a security scheme, Mintlify auto-generates a description for the `Authorization` field in the API playground. Override this text by adding a `description` field to the security scheme in your OpenAPI specification.
-
-```json {6}
-{
- "components": {
- "securitySchemes": {
- "bearerAuth": {
- "type": "http",
- "scheme": "bearer",
- "description": "Your API key from the [dashboard](https://example.com/dashboard). Prefix with `Bearer ` when sending the header."
- }
- }
- }
-}
-```
-
-The `description` field supports Markdown and appears in place of the auto-generated text on every endpoint that uses the security scheme.
-
## Let visitors download your spec
Opt into a "Download API spec" entry in the [page context menu](/organize/settings-structure#contextual) by adding `"download-spec"` to `contextual.options` in your `docs.json`:
From 8575b18ca40d7ba81332c537973145b8e9268316 Mon Sep 17 00:00:00 2001
From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com>
Date: Tue, 21 Jul 2026 05:36:13 +0000
Subject: [PATCH 3/5] docs: add troubleshooting entry for overriding
Authorization field description
---
api-playground/troubleshooting.mdx | 19 +++++++++++++++++++
1 file changed, 19 insertions(+)
diff --git a/api-playground/troubleshooting.mdx b/api-playground/troubleshooting.mdx
index 90d041a102..d0a972eab1 100644
--- a/api-playground/troubleshooting.mdx
+++ b/api-playground/troubleshooting.mdx
@@ -106,6 +106,25 @@ If your API pages aren't displaying correctly, check these common configuration
2. **Invalid operations**: Operations with validation errors in the OpenAPI spec may be skipped. Check your OpenAPI document for syntax errors.
3. **Manual vs automatic inclusion**: If you reference any endpoints from an OpenAPI spec, only the explicitly referenced operations appear in navigation. No other pages are automatically added. This includes operations that are referenced in child navigation elements.
+
+ Mintlify auto-generates a description for the `Authorization` field in the API playground based on the security scheme type. Override it by adding a `description` to the security scheme in your OpenAPI specification.
+
+ ```json {7} theme={null}
+ {
+ "components": {
+ "securitySchemes": {
+ "bearerAuth": {
+ "type": "http",
+ "scheme": "bearer",
+ "description": "Your API key from the [dashboard](https://example.com/dashboard). Send it as `Bearer `."
+ }
+ }
+ }
+ }
+ ```
+
+ The `description` supports Markdown and replaces the auto-generated text on every endpoint that uses the security scheme.
+
When combining OpenAPI operations with regular documentation pages in navigation:
From b709c677b756104be40caa2eb559c852fdc25d27 Mon Sep 17 00:00:00 2001
From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com>
Date: Tue, 21 Jul 2026 10:42:15 -0700
Subject: [PATCH 4/5] Apply suggestions from code review
Co-authored-by: Ethan Palm <56270045+ethanpalm@users.noreply.github.com>
---
api-playground/troubleshooting.mdx | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/api-playground/troubleshooting.mdx b/api-playground/troubleshooting.mdx
index d0a972eab1..d7fdf75ba9 100644
--- a/api-playground/troubleshooting.mdx
+++ b/api-playground/troubleshooting.mdx
@@ -109,7 +109,7 @@ If your API pages aren't displaying correctly, check these common configuration
Mintlify auto-generates a description for the `Authorization` field in the API playground based on the security scheme type. Override it by adding a `description` to the security scheme in your OpenAPI specification.
- ```json {7} theme={null}
+
{
"components": {
"securitySchemes": {
From 89af6b1f74ea0f380951795e463160266f10d471 Mon Sep 17 00:00:00 2001
From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com>
Date: Tue, 21 Jul 2026 10:42:56 -0700
Subject: [PATCH 5/5] Apply suggestion from @ethanpalm
---
api-playground/troubleshooting.mdx | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/api-playground/troubleshooting.mdx b/api-playground/troubleshooting.mdx
index d7fdf75ba9..e5ac6f9418 100644
--- a/api-playground/troubleshooting.mdx
+++ b/api-playground/troubleshooting.mdx
@@ -109,7 +109,7 @@ If your API pages aren't displaying correctly, check these common configuration
Mintlify auto-generates a description for the `Authorization` field in the API playground based on the security scheme type. Override it by adding a `description` to the security scheme in your OpenAPI specification.
-
+ ```json {7}
{
"components": {
"securitySchemes": {