DOCSEARCHbyAlgolia
Submit Docs

redocusaurus

repository·main·Indexed 20 days ago

https://github.com/rohit-gohri/redocusaurus

A Docusaurus preset that integrates Redoc to render OpenAPI documentation within Docusaurus sites. It consists of a main preset package, docusaurus-plugin-redoc for parsing OpenAPI specs, and docusaurus-theme-redoc for providing a theme-compatible wrapper around RedocStandalone with dark mode support.

Tokens
13K
Snippets
40
Records
62
Agent score
72%

What's inside redocusaurus

  1. What is Redocusaurus?

    main

    Redocusaurus is a Docusaurus preset designed to integrate OpenAPI documentation into your Docusaurus site using Redoc. It allows API documentation to coexist with your other documentation while maintaining a consistent look and feel.

    Key features include:

    • TypeScript support: Built with in-built types for better developer experience.
    • Easy setup: Integrated with Docusaurus themes and supports Dark Mode out of the box.
    • Customizability: Allows you to pass custom Redoc options and use Docusaurus Swizzling to modify components.

  2. Understand the Redocusaurus package structure

    main

    Redocusaurus is composed of several specialized packages:

    • redocusaurus: A Docusaurus Preset that combines the theme and plugin packages to simplify adding API documentation to your site.
    • docusaurus-theme-redoc: A wrapper around RedocStandalone designed to match the Docusaurus Theme, including built-in support for Dark Mode.
    • docusaurus-plugin-redoc: A content plugin that automatically generates pages from your OpenAPI files or URLs and renders them using the Redoc component.
    • website: The documentation website and example project used to showcase the preset.

  3. Display OpenAPI documentation using the Redoc component

    main

    The <Redoc /> component supports several ways to provide an OpenAPI specification:

    1. Default (No props): Displays the first element defined in your redocusaurus configuration in docusaurus.config.js.
    2. Via url prop: Loads a specification from an external URL.
    3. Via id prop: Looks up a specific OpenAPI spec defined in your docusaurus.config.js by its ID.
    4. Via spec prop: Passes a JSON object directly. Note that when passing a JSON spec via import, Docusaurus loads the file at build time without pre-processing, which may result in missing features compared to the plugin's standard processing.
    import Redoc from '@theme/Redoc';

// Basic (uses first config element)
<Redoc />

// External URL
<Redoc url="https://redocly.github.io/redoc/openapi.yaml" />

// Using a specific ID from docusaurus.config
<Redoc id="using-single-yaml" />

// Passing JSON spec directly
import openApi from './api-with-examples.json';
<Redoc spec={openApi} />

  5. Understand Build Time Rendering in Redocusaurus

    main

    Redocusaurus now uses build-time rendering by default. This process parses the OpenAPI schema during the Docusaurus build phase and uses a custom webpack configuration to server-render Redoc and include the necessary stylesheets.

    Benefits:

    • Skips the initial loading screen.
    • Improves performance by pre-rendering the documentation.
    • Allows the documentation to be viewable even when JavaScript is disabled in the browser.

  6. Set up the Redocusaurus development environment

    main

    Redocusaurus is a monorepo managed with Yarn Workspaces. To set up the local development environment, follow these steps:

    1. Install all dependencies using yarn.
    2. Build all projects and the website using yarn build && yarn build:website.
    3. To run the packages in development (watch) mode, use yarn dev in one terminal, and in a separate terminal, run yarn dev:website for the website.
    # Install dependencies
yarn

# Build all projects
yarn build && yarn build:website

# Run packages in Dev (Watch) mode
yarn dev

# Run website in Dev mode (in a separate terminal)
yarn dev:website

  8. Render API operations in Docusaurus Docs using ApiOperation

    main

    The ApiOperation component allows you to import specific operation definitions from your OpenAPI schema and render them directly within your Docusaurus documentation pages.

    Important Requirements:

    • You must use the .mdx file extension for any documentation file that imports the ApiOperation component. Standard .md files do not support React component imports.
    • The pointer prop uses JSON Pointer syntax. Note that forward slashes (/) in your API paths must be escaped as ~1 (e.g., /pet becomes ~1pet).
    import ApiOperation from '@theme/ApiOperation';

<ApiOperation pointer="#/paths/~1pet/post" />

  9. Migrate plugin configuration to V1

    main

    When migrating to V1, several configuration keys in the Redocusaurus plugin have changed or been removed:

    Changed Options

    • spec: Now accepts a path to a local file, an absolute URL, or an entrypoint for a multi-file OpenAPI definition (which will be bundled automatically).
    • routePath $\rightarrow$ route (optional): The key has been renamed to route. It is now optional.
    • redocOptions $\rightarrow$ options (optional): Renamed to options. Note that some previous defaults (like downloadUrl) are no longer automatically applied; you must now configure them explicitly if needed.

    Removed Options

    • specUrl: Removed. The spec option now handles both local paths and URLs automatically. The package will bundle definitions into a single downloadable YAML static asset at build time.
    • addRoute: Removed. Since route is now optional, you can simply omit the key if a custom route is not required.
    • apiDocComponent: Removed. Use the @theme/useSpecData hook instead to load plugin data for the @theme/Redoc component.

  11. Use multiple OpenAPI schemas with ApiOperation

    main

    When managing multiple APIs in your Redocusaurus configuration, assign a unique id to each spec in docusaurus.config.js. You can then reference these IDs in the ApiOperation component to ensure the correct operation is rendered from the correct schema.

    // docusaurus.config.js
const config = {
  presets: [
    '@docusaurus/preset-classic',
    [
      'redocusaurus',
      {
        specs: [
          {
            id: 'using-single-yaml',
            spec: 'openapi/single-file/openapi.yaml',
            route: '/examples/using-single-yaml/',
          },
          {
            id: 'using-remote-url',
            spec: 'https://redocly.github.io/redoc/openapi.yaml',
            route: '/examples/using-remote-url/',
          },
        ],
      },
    ],
  ],
};

// In your .mdx file
import ApiOperation from '@theme/ApiOperation';

<ApiOperation id="using-single-yaml" pointer="#/paths/~1pet/post" />
<ApiOperation id="using-remote-url" pointer="#/paths/~1pet/post" />

  12. Display multiple APIs using a nested view with MDX

    main

    To display multiple API documentation sets while retaining the standard Docusaurus sidebar for navigation, use the @theme/ApiDocMdx component within an MDX file.

    To ensure the API documentation doesn't conflict with the Docusaurus page structure, you should set hide_table_of_contents: true in the MDX file's frontmatter. This allows the Redoc UI to take precedence in the layout.

    Pass the id of the OpenAPI specification (the identifier used in your configuration) to the <ApiDocMdx /> component.

    ---
title: API 1 - Swagger Petstore
hide_table_of_contents: true
---

import ApiDocMdx from '@theme/ApiDocMdx';

<ApiDocMdx id="using-single-yaml" />