Docusaurusは、Facebook社が開発したオープンソースの静的サイトジェネレーターです。主に技術文書やAPIリファレンスの構築に使われています。ただし、DocusaurusはAPIドキュメンテーション専用なツールではないため、一部の課題もあると指摘されています。本文では、DocusaurusのMarkdownファイル、または構築したWebページを簡単にApidogに移行する方法を皆さんに紹介します。
Docusaurusについて
Docusaurusは、Facebook社が開発したオープンソースの静的サイトジェネレーターです。主に技術文書やAPIリファレンスの構築に使われています。Docusaurusは、Markdownフォーマットに完璧に互換しているため、Markdown形式で記述したドキュメントを自動的にWebページに変換することができます。
APIドキュメンテーション作成中の課題
Docusaurusは基本的にAPIドキュメンテーションの作成に向いているツールですが、完全にAPIドキュメンテーション専用ではないため、次のような一部の課題があります。
- APIリファレンスへの特化が足りない
Docusaurusは汎用的な技術文書作成ツールなので、APIリファレンス特有の機能(パラメータ定義、リクエスト/レスポンス例の強調表示など)が不足している可能性があります。 - APIスペックとの連携がない
APIスペックをベースにドキュメンテーションを自動生成する機能がないため、手動で記述する必要があります。OpenAPIなどのスペック駆動開発と連携できません。 - バージョン管理の課題
APIのリソースパスやパラメータがバージョンアップで変更された場合、Docusaurusの機能だけでは追跡が難しい可能性があります。 - プラグインエコシステムの未成熟
APIドキュメンテーション専用のプラグインがまだ十分ではないため、カスタマイズが難しい側面があります。
このため、APIドキュメンテーション作成専用のツールと比べると、Docusaurusは汎用的すぎる側面があります。そこで、Docusaurusの代替品を探している方に、Apidogというツールをお勧めします。Apidogは、Markdownフォーマットに完璧に互換できる一方、APIのスペックから直感的で綺麗なAPIドキュメンテーションの生成をもサポートしているので、APIリファレンスを作成してみたい方にとって、一番適切なオプションになります。
ApidogのMarkdownについて：https://markdown-jp.apidog.io/
DocusaurusのファイルをApidogに移行
そこで、本文では、DocusaurusのファイルをApidogに移行して、より万全なAPIリファレンスを構築する対策を皆さんに紹介します。
Apidogは、様々なMarkdown記法にも対応でき、MarkdownファイルをDocusaurusのように自動的にWebページに変換することができます。その上、APIスペックファイルから綺麗なAPIドキュメンテーションを生成することができますので、Markdown形式のWebページとAPIドキュメンテーションページを一緒にリストすることが可能です。
DocusaurusからApidogへの移行により、APIドキュメンテーションの作成・管理がより適切に行えるようになる点は非常に有益だと思います。
移行の要件
DocusaurusのファイルをApidogに移行するには、次のものをあらかじめ用意する必要があります：
- Apidogのアカウント：お持ちでない方は、今すぐApidogに登録しましょう。
- ウェブサイトのオリジナルなMarkdownファイル：基本的にはプロジェクト内の
docs/やblog/フォルダーに保存されています。
1. ApidogでHTTPプロジェクトを作成
ApidogでHTTPプロジェクトを作成します。
2. DocusaurusのMarkdownファイルをApidogに移行
HTTPプロジェクトを作成すると、左側メニューから「設定」→「データをインポート」の順に選択し、「Markdown」を選択します。ここでDocusaurusのMarkdownファイルをインポートします。
- MarkdownファイルをApidogにインポートする場合、Markdownのファイル名を自分で定義することができます。Markdownファイルをファイル名を変更せずApidogにインポートすることもできますし、ファイル内容の第1行をファイル名に設定したままでApidogにインポートすることもできます。
3. Markdownファイルの編集
Markdownファイルを成功にインポートすると、Apidogでこのファイルを簡単に編集することもできます。
- Docusaurusとは異なり、Markdownファイルの他に、APIドキュメンテーションの作成にも対応しています。APIスペックファイルからドキュメンテーションページを簡単に生成すると、APIドキュメントをMarkdownファイルと一緒にリストすることも可能です。
4. プロジェクトを公開
編集が終わった場合、プロジェクトを公開することができます。左側メニューから「共有」→「公開設定」で、プロジェクトを公開することができます。
- カスタムドメインの利用：Apidogを利用して、プロジェクトを自分のドメインにデプロイすることが可能です。「カスタムドメイン」の編集ボタンをクリックして、当該ドメインの所有権認証を通すと、このプロジェクトを指定のドメインにデプロイすることが可能です。
5. 移行済みのプロジェクトを確認
Apidogでプロジェクトを公開すると、自分で定義したドメインにアクセスすると、プロジェクトのページを確認することができます。ここで全てのMarkdownファイルが自動的にWebページに変換され、APIスペックもドキュメンテーションのページに自動的に変換されます。
まとめ
本記事では、DocusaurusのファイルをApidogに移行する手順を詳しく解説しました。
DocusaurusはAPIドキュメンテーション作成に向いているものの、一部の課題があります。一方、Apidogはマークダウンに完全対応しつつ、APIスペックからのドキュメンテーション自動生成など、APIドキュメンテーション作成に特化した機能を備えています。DocusaurusのマークダウンファイルをそのままインポートできるApidogは、APIリファレンスの作成・管理をスムーズに行えるツールです。本記事で解説した手順を参考に、Docusaurusの資産をApidogに移行することをおすすめします。
Apidogへの移行により、以下のようなメリットが期待できます。
- マークダウンとAPIドキュメンテーションの一元管理
- APIスペック駆動による効率化
- バージョン管理やカスタマイズ機能の充実
- カスタムドメインへの公開が可能
APIドキュメンテーションの品質向上とメンテナンス性の両立を目指す際には、Apidogは有力な選択肢となるでしょう。本記事が移行の一助となれば幸いです。
