【Docusaurus】Docusaurusを使ってOpenAPIからAPIドキュメントを自動生成する

本記事の目的

• Docusaurusを使ってAPIドキュメントを作成することができる
• OpenAPIドキュメントからAPIドキュメントを自動生成することができる

Docusaurusとは

「Docusaurus（ドキュサウルス）」とは、Facebook社（現Meta社）によって開発・メンテナンスされている静的サイトジェネレータです。

1. Docusaurusの初期設定

以下コマンドで、Docusaurusのアプリケーション「api-doc-sample」が作成されます。

$ npx create-docusaurus@latest api-doc-sample classic

作成されたフォルダに移動して start コマンドを実行すると、http://localhost:3000 に開発用サーバーが起動します。

$ cd api-doc-sample
$ npm run start

2. OpenAPIドキュメントを用意

ベースとなるOpenAPIドキュメントをプロジェクトフォルダ内に配置します。

openapi/openapi.yaml

openapi: 3.1.0
info:
  title: User API (Sample)
  version: 1.0.0
  description: |
    A sample OpenAPI document for retrieving user information.

servers:
  - url: https://dummyjson.com

paths:
  /users/{id}:
    get:
      operationId: getUser
      summary: Get a user
      description: Returns information about a specific user by ID.
      tags:
        - Users
      parameters:
        - name: id
          in: path
          required: true
          description: The ID of the user to retrieve
          schema:
            type: string
            example: "user_123"
      responses:
        "200":
          description: Successfully retrieved user
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/User"
              example:
                id: "user_123"
                name: "John Doe"
                email: "[e-mail]"
                createdAt: "2025-01-15T10:00:00Z"
        "404":
          description: User not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                code: "NOT_FOUND"
                message: "The specified user does not exist."

components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: string
          example: "user_123"
        name:
          type: string
          example: "John Doe"
        email:
          type: string
          format: email
          example: "[e-mail]"
        profilePicture:
          type: string
          format: url
          example: "https://dummyjson.com/image/1.jpg"
        createdAt:
          type: string
          format: date-time
          example: "2025-01-15T10:00:00Z"
      required:
        - id
        - name
        - email
        - createdAt

    Error:
      type: object
      properties:
        code:
          type: string
          example: "NOT_FOUND"
        message:
          type: string
          example: "The specified user does not exist."
      required:
        - code
        - message

3. プラグインのインストール・初期設定

今回は、PaloAltoNetworks によって開発・メンテナンスされている「docusaurus-openapi-docs」というプラグインを使用します。

以下コマンドで、プラグインとテーマをインストールします。

$ npm install docusaurus-plugin-openapi-docs docusaurus-theme-openapi-docs

docusaurus.config.ts に、インストールしたプラグインの設定を追記します。

docusaurus.config.ts

// ...
+ import type * as Plugin from "@docusaurus/types/src/plugin";
+ imaport type * as OpenApiPlugin from "docusaurus-plugin-openapi-docs";

const config: Config = {
  // ...
  presets: [
    [
      'classic',
      {
        docs: {
          // ...
+         docItemComponent: "@theme/ApiItem",
        },
        // ...
      } satisfies Preset.Options,
    ],
  ],

+ plugins: [
+   [
+     'docusaurus-plugin-openapi-docs',
+     {
+       id: "api",
+       docsPluginId: "classic",
+       config: {
+         sample: {
+           specPath: "openapi/openapi.yaml", // OpenAPIドキュメントのファイルパス
+           outputDir: "docs/api", // ドキュメント（mdx）出力先のフォルダパス
+           sidebarOptions: {
+             groupPathsBy: "tag",
+           },
+         } satisfies OpenApiPlugin.Options,
+       }
+     },
+   ]
+ ],
+ themes: ["docusaurus-theme-openapi-docs"],

  // ...
};

4. ドキュメントを生成する

以下コマンドを実行すると、specPath で指定したOpenAPIからドキュメント生成が実行されます。

$ npx docusaurus gen-api-docs all

以下のようなログが出力されれば、正常にドキュメント生成が完了しています。
outputDir で指定したフォルダパスに、sidebar.ts、.info.mdx、.api.mdx がそれぞれ作成されます。

Successfully created "docs/api"
Successfully created "docs/api/sidebar.ts"
Successfully created "docs/api/user-api-sample.info.mdx"
Successfully created "docs/api/get-user.api.mdx"

.api.mdx は、エンドポイント毎に作られる実際のドキュメントページに該当するファイルです。OpenAPIで定義されている各エンドポイントの operationId（または summary） の値をキャメルケースにしたものが、そのままファイル名となります。

sidebar.ts と .info.mdx は、docusaurus.config.ts の config 毎に作成されます。

ブラウザで確認すると、以下のようにAPIドキュメントのページが閲覧できます。

注意点として、gen-api-docs コマンドは各エンドポイントの operationId（または summary）の値毎に作成済みかどうかを判定しています。
その為、一度ドキュメントを作成すると、例えば各エンドポイントのパラメータなどを更新しても自動で各ページの更新はされません。

なので、一度 clean-api-docs コマンドを実行してから gen-api-docs コマンドを実行して、全てのページを再度作成しなおすのがシンプルです。

$ npx docusaurus clean-api-docs all
$ npx docusaurus gen-api-docs all

Tips

サンプルコードについて

生成されるページの右上には、言語毎のサンプルコードを閲覧できるセクションが生成されます。

表示する言語は、docusaurus.config.ts の config.themeConfig.languageTabs から指定することができます。指定が無い場合は、全ての言語が表示された状態となります。

以下では、表示する言語を Node.js のみにしています。

docusaurus.config.ts

const config: Config = {
  // ...
  themeConfig: {
    // ...
    languageTabs: [
      {
        language: 'nodejs',
        highlight: 'javascript',
        logoClass: 'nodejs',
        variants: ['axios'],
      },
    ]
    
  }
};

以下は、それぞれのオプションで指定できる値です。

language	highlight	variants
curl	bash	curl
python	python	requests, http.client
go	go	native
nodejs	javascript	axios, native, request, unirest
ruby	ruby	net::http
csharp	csharp	httpclient, restsharp
php	php	curl, guzzle, pecl_http, http_request2
java	java	okhttp, unirest
powershell	powershell	restmethod
dart	dart	dio, http
javascript	javascript	fetch, jquery, xhr
kotlin	kotlin	okhttp
c	c_cpp	libcurl
objective-c	objectivec	nsurlsession
ocaml	ocaml	cohttp
r	r	httr, rcurl
rust	rust	reqwest
swift	swift	urlsession
http	http	http

ダミーリクエストについて

生成されるページの右下には、リクエストをテスト送信できるセクションが生成されます。

クエリパラメータ、パスパラメータ、リクエストボディは input できるようになっており、送信ボタンを押下することで実際にリクエストを送信することができます。

ベースURLは、OpenAPIドキュメントの servers.url の値になります。

openapi: 3.1.0
info:
  title: User API (Sample)
  version: 1.0.0
  description: |
    A sample OpenAPI document for retrieving user information.

servers:
  - url: https://dummyjson.com # ベースURL