Update MDX Files from OpenAPI
After changing API routes (for example on localhost:9001), the Docusaurus OpenAPI docs must be regenerated so the MDX files reflect the new spec. The plugin does not overwrite existing files, so you need to clean the generated docs first, then regenerate them.
Prerequisites
- The API serving the OpenAPI/Swagger spec must be running (e.g.
http://localhost:9001). - The spec URL is configured in
docusaurus.config.ts(e.g.http://localhost:9001/api-docs/exame.jsonfor exam routes).
Steps
1. Clean the generated API docs
Remove the existing generated MDX files and sidebar for the plugin you want to update. Use the plugin ID defined in docusaurus.config.ts.
To clean all specs of a given plugin (e.g. exam routes only):
bash
Example — clean only exam routes:
bash
Example — clean all API docs (all plugins):
bash
If you have more than one OpenAPI plugin, you must use
-p <plugin-id>. Otherwise the command will ask you to specify the plugin.
2. Regenerate the API docs
Regenerate the MDX files from the current OpenAPI spec. Ensure the API is running so the spec URL is reachable.
To regenerate only the docs for one plugin:
bash
Example — regenerate exam routes:
bash
Example — regenerate all API docs:
bash
3. Verify
Check that the updated routes and schemas appear in docs/openapi/legacy-api/<category>/ and that the sidebar and MDX content match your API.
Quick reference
| Goal | Command |
|---|---|
| Clean exam docs only | pnpm docusaurus clean-api-docs all -p legacy-api-exam-routes |
| Regenerate exam docs | pnpm gen-api-docs -p legacy-api-exam-routes |
| Clean + regenerate exam | Run the two commands above in order |
| Clean all API docs | pnpm docusaurus clean-api-docs all (use -p if multiple plugins) |
| Regenerate all | pnpm gen-api-docs |
Plugin IDs (from docusaurus.config.ts)
legacy-api— legacy APIlegacy-api-exam-routes— exam routeslegacy-api-authentication-routes— authentication routeslegacy-api-logout-routes— logout routes
Use the same plugin ID for both clean-api-docs and gen-api-docs when updating a specific set of routes.