From d1bbaeec70e2c24fd9aeb9f28dd0cdc6e1869d72 Mon Sep 17 00:00:00 2001
From: Hamed Rabah <26891088+hamedrabah@users.noreply.github.com>
Date: Thu, 27 Aug 2026 14:52:57 -0700
Subject: [PATCH] docs: explain localhost OpenAPI previews

---
 api-playground/openapi-setup.mdx | 23 +++++++++++++++++++++++
 1 file changed, 23 insertions(+)

diff --git a/api-playground/openapi-setup.mdx b/api-playground/openapi-setup.mdx
index 665d9024c..c13f27b7b 100644
--- a/api-playground/openapi-setup.mdx
+++ b/api-playground/openapi-setup.mdx
@@ -45,6 +45,29 @@ Reference any number of OpenAPI specifications in the navigation element of your
   Mintlify supports `$ref` for **internal references only** within a single OpenAPI document. Mintlify does not support external references.
 </Note>
 
+### Use a localhost specification
+
+During local development, you can generate an OpenAPI document from a service running on your machine and reference its localhost URL:
+
+```json
+"navigation": {
+  "tabs": [
+    {
+      "tab": "API Reference",
+      "openapi": "http://localhost:8000/openapi.json"
+    }
+  ]
+}
+```
+
+Pass `--local-schema` to allow the CLI to fetch the specification over HTTP:
+
+```bash
+mint dev --local-schema
+```
+
+To validate the same configuration without starting a preview, run `mint validate --local-schema`. Production deployments require OpenAPI URLs to use HTTPS.
+
 ### Describe your API
 
 Use the following resources to learn about and construct your OpenAPI specification.