docusaurusにopenapiを突っ込んでredocで見れるようにする

redoc on Docusaurusがしたいと思ったことが結構あります。

理由は単純で、Github PagesでDocusaurus製のドキュメントを作ってさらにRedocを置くとなると場所が足りないからです。
なんか頑張ればサブディレクトリとかでどうにかできなくもなさそうな気がするんですが、仮にできてもそれぞれのドキュメントをまたぐ際などに手間がかかるのであまりスマートではない気がします。

なので、Docusaurus上でいい感じにOpenAPIのファイルを表示してくれるプラグインかなにかはないかと探していました。

そんな中で見つけたのが、redocusaurusです。もう直球ですね。

redocusaurusを試す

これです

以下のコマンドを実行します。

npx create-docusaurus@latest <project_name> classic
cd <project_name>
npm intall redocusaurus

次にconfigの一部を下のように変更

  presets: [
    // Redocusaurus config
    [
      "redocusaurus",
      {
        // Plugin Options for loading OpenAPI files
        specs: [
          {
            id: "sample_file",
            spec: "https://redocly.github.io/redoc/openapi.yaml",
            route: "/api/",
          },
        ],
        // Theme Options for modifying how redoc renders them
        theme: {
          // Change with your site colors
          primaryColor: "#1890ff",
        },
      },
    ],
    [
      "classic",
      /** @type {import('@docusaurus/preset-classic').Options} */
      ({
        docs: {
          sidebarPath: require.resolve("./sidebars.js"),
          // Please change this to your repo.
          // Remove this to remove the "edit this page" links.
          editUrl:
            "https://github.com/facebook/docusaurus/tree/main/packages/create-docusaurus/templates/shared/",
        },
        blog: {
          showReadingTime: true,
          // Please change this to your repo.
          // Remove this to remove the "edit this page" links.
          editUrl:
            "https://github.com/facebook/docusaurus/tree/main/packages/create-docusaurus/templates/shared/",
        },
        theme: {
          customCss: require.resolve("./src/css/custom.css"),
        },
      }),
    ],
  ],

docs配下にapiディレクトリを作成し、中で任意の名前のmdxファイルを作成

api1.mdx

---
title: API 1
hide_table_of_contents: false
---

import ApiDocMdx from '@theme/ApiDocMdx';

<ApiDocMdx id="sample_file"/>;

sidebar.jsを書き換えて、出しわけるように修正

const path = require("node:path");
const fs = require("node:fs");

const getMarkdownFileNamesInDir = (dirPath) =>
  fs
    .readdirSync(dirPath)
    .filter((filename) => filename.includes(".md"))
    .map((filename) => `tutorial-basics/${path.parse(filename).name}`);

/** @type {import('@docusaurus/plugin-content-docs').SidebarsConfig} */
const sidebars = {
  tutorialSidebar: [
    "intro",
    {
      type: "category",
      label: "Tutorial",
      items: getMarkdownFileNamesInDir("docs/tutorial-basics"),
    },
  ],
  api: ["api/api1"],
};

headerにOpenAPI用の項目を追加

...
themeConfig:
    /** @type {import('@docusaurus/preset-classic').ThemeConfig} */
    ({
      navbar: {
        title: "My Site",
        logo: {
          alt: "My Site Logo",
          src: "img/logo.svg",
        },
        items: [
          {
            type: "doc",
            docId: "intro",
            position: "left",
            label: "Tutorial",
          },
          { to: "/blog", label: "Blog", position: "left" },
          {
            type: "doc",
            docId: "api/api1",
            position: "left",
            label: "OpenAPI",
          },
          {
            href: "https://github.com/facebook/docusaurus",
            label: "GitHub",
            position: "right",
          },
        ],
      },
      footer: {...

これで準備は整ったので、Docusaurusを立ち上げます

npm run start

開いてHeaderからOpenAPIを選ぶとこんな感じになります

デフォルトではちょっと細身ですが、まあいい感じですね。
幅に関しては自身で任意の幅に調整できるので、好きにいじってください。

おわりに

Docusaurusが8月にversion2をリリースしました。
リリースノート見るまで特に違いに気が付いてなかったので目を見張るほど変わったってわけではないんですが、MDXのサポートだったりいろいろ良くなった印象です。
redocusaurus以外にも色々面白そうなプラグインも公式ドキュメントで紹介されているので、もし興味があったら見に行ってみてください。