mirror of
https://github.com/mintlify/docs.git
synced 2026-09-14 13:35:46 +08:00
Ethan Palm
db3ca0500d
* update skills * update migration guide * update API migration guide * update assistant page * update analytics page * update CLI commands * deprecate openapi-check * add coming soon * update docs.json * add index page * add install page * add preview page * add analytics * add commands reference * update links * delete installation.mdx * add optional prereq steps * Add telemetry section to commands reference Incorporates telemetry content from #5039 which was merged to main after this branch was created. Documents opt-out flags, env variables, and config persistence. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * move global flags to top * vale * remove `mint upgrade` * remove unnecessary prereq * restructure analytics commands --------- Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
111 lines
3.2 KiB
Plaintext
111 lines
3.2 KiB
Plaintext
---
|
|
title: "Migrating MDX API pages to OpenAPI navigation"
|
|
sidebarTitle: "Migrate from MDX to OAS"
|
|
description: "Migrate your manually written MDX API pages to automated OpenAPI-generated documentation with flexible navigation and endpoint grouping."
|
|
keywords: ["API migration", "OpenAPI migration", "x-mint extension"]
|
|
---
|
|
|
|
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.
|
|
|
|
## 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#customize-your-endpoint-pages) 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": {
|
|
"groups": [
|
|
{
|
|
"group": "API Reference",
|
|
"openapi": "/path/to/openapi.json",
|
|
"pages": [
|
|
"overview",
|
|
"authentication",
|
|
"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": {
|
|
"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:
|
|
|
|
```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.
|