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. This can help you reduce the number of files you need to maintain and improve the consistency of your API documentation. You can define metadata and content for each endpoint in your OpenAPI specification and organize endpoints where you want them in your navigation.

​
CLI migration

The mint migrate-mdx command is the recommended way to migrate from MDX endpoint pages to autogenerated pages. This command:
  • Parses your docs.json navigation structure.
  • Identifies MDX pages that generate OpenAPI endpoint pages.
  • Extracts content from MDX files and moves it to the x-mint extension in your OpenAPI specification.
  • Updates your docs.json to reference the OpenAPI endpoints directly instead of MDX files.
  • Deletes the original MDX endpoint files.
If you already have x-mint defined for an endpoint and also have an MDX page with content for that endpoint, the MDX content will overwrite existing x-mint settings.If you have multiple MDX pages for the same endpoint with different content, the script will use the content from the page that appears last in your docs.json.The migration tool does not support previewing changes before applying them.
1

Prepare your OpenAPI specification.

Ensure your OpenAPI specification is valid and includes all endpoints you want to document.Any MDX pages you want to migrate must have the openapi: frontmatter referencing an endpoint.
Validate your OpenAPI file using the Swagger Editor or Mint CLI.
2

Install the Mint CLI

If needed, install or update the Mint CLI.
3

Run the migration command.

mint migrate-mdx

​
Manual migration steps

1

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 for more details.For any endpoints that you want to exclude from your documentation, add the x-hidden extension to the endpoint.
Validate your OpenAPI file using the Swagger Editor or Mint CLI.
2

Update your navigation structure.

Replace MDX page references with OpenAPI endpoints in your docs.json.
"navigation": {
  "groups": [
    {
      "group": "API Reference",
      "openapi": "/path/to/openapi.json",
      "pages": [
        "overview",
        "authentication",
        "introduction",
        "GET /health",
        "quickstart", 
        "POST /users",
        "GET /users/{id}",
        "advanced-features"
      ]
    }
  ]
}
3

Remove old MDX files.

After verifying your new navigation works correctly, remove the MDX endpoint files that you no longer need.
You can customize how your API documentation appears in your navigation.

​
Mixed content navigation

Combine automatically generated API pages with other pages: 
"navigation": {
  "groups": [
    {
      "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: 
"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.