Skip to main content

Pairing with renderers

docusaurus-plugin-omg only compiles OMG to OpenAPI — it deliberately doesn't render anything. Once the spec is on disk, you choose how to display it.

Three common pairings:

Redocusaurus (Redoc)​

Redocusaurus wraps Redoc as a Docusaurus plugin and reads OpenAPI specs from disk or a URL.

npm install redocusaurus
docusaurus.config.ts
plugins: [
  ['docusaurus-plugin-omg', { apis: [{ id: 'todo', input: 'api/todo/api.omg.md' }] }],
  [
    'redocusaurus',
    {
      specs: [
        {
          // Same path the omg plugin writes to.
          spec: 'static/api/todo.yaml',
          route: '/api/todo',
        },
      ],
    },
  ],
],

Visit /api/todo to see the rendered spec. Order matters: the omg plugin must run before any plugin that reads its output.

docusaurus-plugin-openapi-docs​

docusaurus-plugin-openapi-docs generates per-endpoint MDXMDX A Markdown-based format that lets you write JSX inside your markdown, used by Docusaurus v3 for docs and pages. pages with built-in code samples and request/response panels.

plugins: [
  ['docusaurus-plugin-omg', { apis: [{ id: 'todo', input: 'api/todo/api.omg.md' }] }],
  [
    'docusaurus-plugin-openapi-docs',
    {
      id: 'apis',
      docsPluginId: 'classic',
      config: {
        todo: {
          specPath: 'static/api/todo.yaml',
          outputDir: 'docs/api/todo',
          sidebarOptions: { groupPathsBy: 'tag' },
        },
      },
    },
  ],
],

Run npx docusaurus gen-api-docs once the omg plugin has produced the spec, then check the generated MDXMDX A Markdown-based format that lets you write JSX inside your markdown, used by Docusaurus v3 for docs and pages. into source.

Standalone Swagger UI​

If you just want a single embeddable page without another plugin, drop a Swagger UI HTML page into static/:

static/api/todo.html
<!doctype html>
<html>
  <head>
    <link rel="stylesheet" href="https://unpkg.com/swagger-ui-dist@5/swagger-ui.css" />
  </head>
  <body>
    <div id="swagger-ui"></div>
    <script src="https://unpkg.com/swagger-ui-dist@5/swagger-ui-bundle.js"></script>
    <script>
      window.onload = () =>
        SwaggerUIBundle({
          url: '/api/todo.yaml',
          dom_id: '#swagger-ui',
        })
    </script>
  </body>
</html>

Visit /api/todo.html. No build step required, no extra dependencies.

Just the raw spec​

You don't need a renderer at all. The compiled spec is a regular static asset — link to /api/todo.yaml from a doc page and let consumers download it for use in tools like Postman, Insomnia, or their own pipelines.

Choosing​

You want…Pick
A single, beautiful reference pageRedocusaurus
Per-endpoint MDXMDX A Markdown-based format that lets you write JSX inside your markdown, used by Docusaurus v3 for docs and pages. pages with code samples + try-it consolesdocusaurus-plugin-openapi-docs
Zero extra dependenciesStatic Swagger UI HTML
Just a downloadable specLink to /api/<id>.yaml directly