Import Swagger JSON

How to import Swagger JSON from API to Docusaurus

After preparing the API, you can import your documentation. Docusaurus will transform the swagger JSON into a mdx files. Each file will contain one route.

New docs

Create docs folder

Create the folder where the mdx files will be created. All the routes documentation are kept inside the folder openapi:

text
.
├── docs
│   ├── openapi

Add new plugin

In docusaurus.config.ts, add your configurations to the plugins array. Change the following parameters:

• id - add the id of your plugin using kebab-case (or spinal-case)
• In outputDir add the path to the new folder created.
• In specPath add the api url + route of the json
• The object inside config should have the same name as the id

Example:

text
[
    'docusaurus-plugin-openapi-docs',
    {
        id: 'legacy-api-exam-routes',
        docsPluginId: 'classic',
        config: {
            legacyApiExamRoutes: {
                specPath: 'http://localhost:9001/api-docs/exame.json',
                outputDir: 'docs/openapi/legacy-api/exam',
                sidebarOptions: {
                    groupPathsBy: "tag",
                    categoryLinkSource: "tag",
                },
            } satisfies OpenApiPlugin.Options,
        },
    },
]

Import the JSON

In the cmd, run the command:

text
pnpm gen-api-docs -p `plugin id`

Example

text
pnpm gen-api-docs -p legacy-api-exam-routes

If the docs are exported properlly, you should see a similar message in the cmd:

text
Successfully created "docs/openapi/legacy-api/exam/get-exam-viewer-data.api.mdx"
Successfully created "docs/openapi/legacy-api/exam/processar-e-gerar-pdf.api.mdx"
Successfully created "docs/openapi/legacy-api/exam/remover-exame-anterior-sem-principal.api.mdx"

Updating existing docs