Merge branch 'x-mint' into openapi-nav-updates

Author: ethanpalm

api-playground/mdx/configuration.mdx

@@ -3,7 +3,7 @@ title: 'MDX setup'
 description: 'Generate docs pages for your API endpoints using `MDX`'
 ---
 
-You can manually define API endpoints in individual `MDX` files rather than using an OpenAPI specification. This method provides flexibility for custom content, but we recommend generating API documentation from an OpenAPI specification file for most API documentation projects as it's more maintainable and feature-rich. However, MDX can be useful for documenting small APIs, prototyping, or when you want to feature API endpoints alongside other content.
+You can manually define API endpoints in individual `MDX` files rather than using an OpenAPI specification. This method provides flexibility for custom content, but we recommend generating API documentation from an OpenAPI specification file for most projects because it is more maintainable and feature-rich. However, creating `MDX` pages for an API can be useful to document small APIs or for prototyping.
 
 To generate pages for API endpoints using `MDX`, configure your API settings in `docs.json`, create individual `MDX` files for each endpoint, and use components like `<ParamFields />` to define parameters. From these definitions, Mintlify generates interactive API playgrounds, request examples, and response examples.
 

api-playground/migrating-from-mdx.mdx

@@ -0,0 +1,168 @@
+---
+title: "Migrating MDX API pages to OpenAPI navigation"
+sidebarTitle: "Migrating from MDX"
+description: "Update from individual MDX endpoint pages to automated OpenAPI generation with flexible navigation"
+icon: "arrow-big-right-dash"
+---
+
+If you are currently using individual `MDX` pages for your API endpoints, you can migrate to autogenerating pages from your OpenAPI specification while retaining the customizability of individual pages.
+
+You can define metadata and content for each endpoint in your OpenAPI specification and organize endpoints precisely where you want them in your navigation.
+
+Follow this migration guide to start building your API documentation from your OpenAPI specification with these benefits:
+
+- Automatic page generation from your OpenAPI spec
+- Flexible navigation options
+- Fewer files to maintain
+- Consistent API documentation format
+
+## Before: Individual MDX pages
+
+Previously, you created separate MDX files for each endpoint and referenced them in your navigation:
+
+```json
+{
+  "navigation": [
+    {
+      "group": "API Reference",
+      "pages": [
+        "api/get-users",
+        "api/post-users", 
+        "api/delete-users"
+      ]
+    }
+  ]
+}
+```
+
+Each endpoint required its own MDX file with manual configuration and content.
+
+## After: OpenAPI navigation
+
+When you complete the migration, you will reference your OpenAPI specification directly in navigation and automatically generate endpoint pages:
+
+```json
+{
+  "navigation": [
+    {
+      "group": "API Reference", 
+      "openapi": "openapi.json"
+    }
+  ]
+}
+```
+
+Or selectively include specific endpoints:
+
+```json
+{
+  "navigation": [
+    {
+      "group": "API Reference",
+      "openapi": "openapi.json", 
+      "pages": [
+        "GET /users",
+        "POST /users",
+        "DELETE /users"
+      ]
+    }
+  ]
+}
+```
+
+## Migration steps
+
+<Steps>
+  <Step title="Prepare your OpenAPI specification.">
+    Ensure your OpenAPI specification is valid and includes all endpoints you want to document.
+
+    For any endpoints that you want to customize the metadata or content, add the `x-mint` extension to the endpoint. See [x-mint extension](/api-playground/openapi-setup#x-mint-extension) for more details.
+
+    For any endpoints that you want to exclude from your documentation, add the `x-hidden` extension to the endpoint.
+
+    <Info>
+      Validate your OpenAPI file using the [Swagger Editor](https://editor.swagger.io/) or [Mint CLI](https://www.npmjs.com/package/mint).
+    </Info>
+  </Step>
+  
+  <Step title="Update your navigation structure.">
+    Replace `MDX` page references with OpenAPI endpoints in your `docs.json`.
+
+    ```json
+    {
+      "navigation": {
+        "openapi": "/path/to/openapi.json",
+        "pages": [
+          "introduction",
+          "GET /health",
+          "quickstart", 
+          "POST /users",
+          "GET /users/{id}",
+          "advanced-features"
+        ]
+      }
+    }
+    ```
+
+  </Step>
+
+  <Step title="Remove old MDX files.">
+    After verifying your new navigation works correctly, remove the `MDX` endpoint files that you no longer need.
+  </Step>
+</Steps>
+
+## Navigation patterns
+
+You can customize how your API documentation appears in your navigation.
+
+### Mixed content navigation
+
+Combine automatically generated API pages with other pages:
+
+```json
+{
+  "navigation": [
+    {
+      "group": "API Reference",
+      "openapi": "openapi.json",
+      "pages": [
+        "api/overview",
+        "GET /users",
+        "POST /users", 
+        "api/authentication"
+      ]
+    }
+  ]
+}
+```
+
+### Multiple API versions
+
+Organize different API versions using tabs or groups:
+
+```json
+{
+  "navigation": {
+    "tabs": [
+      {
+        "tab": "API v1",
+        "openapi": "specs/v1.json"
+      },
+      {
+        "tab": "API v2", 
+        "openapi": "specs/v2.json"
+      }
+    ]
+  }
+}
+```
+
+## When to use individual `MDX` pages
+
+Consider keeping individual `MDX` pages when you need:
+
+- Extensive custom content per endpoint like React components or lengthy examples
+- Unique page layouts
+- Experimental documentation approaches for specific endpoints
+
+For most use cases, OpenAPI navigation provides better maintainability and consistency.