Docusaurusは、Facebook社が開発したオープンソースの静的サイトジェネレーターとして、Markdownファイルを自動的にWebページに変換できます。それでは、DocusaurusでAPI仕様書を作成可能ですか？本文では、DocusaurusでAPI仕様書を作成する方法について詳しく論じていくと思います。
DocusaurusでAPI仕様書の作成？
Docusaurusは、主に技術文書やヘルプドキュメントの構築に汎用されている静的サイトジェネレーターになります。ヘルプドキュメントの他に、多くのユーザーは、API仕様書とかAPIリファレンスを作成する必要もあります。ネットワークで情報を検索すると、必要がある方はたくさんいらっしゃるようです：
Create API documentation using Docusaurus. Any ideas?
by u/radsmine in Docusaurus
それでは、API仕様書を作成する必要もある場合は、Docusaurusはそれをサポートできますか？実際には、Docusaurusを使ってAPI仕様書を作成することができます。具体的には、以下の方法に従って作成できています：
- Markdown
Docusaurusでは、Markdownファイルを使ってドキュメントを作成できます。APIの各エンドポイントの説明やリクエスト/レスポンスの例などをMarkdownで書いていけば、API仕様書が作成できます。 - サードパーティのプラグイン
また、Stoplight ElementsやRedocなどのAPI自動ドキュメンテーションツールを使って、API仕様書を生成し、その出力をDocusaurusに組み込むことができます。
Docusaurusの長所は、やはりMarkdownファイルに基づいてWebページを生成して、ウェブサイトとして公開できる点にあります。API仕様書を作成する場合、コードサンプルやチュートリアル、ガイドなども追加して、包括的なページを構築することができます。
DocusaurusでAPI仕様書の作成の課題
上記のように、Markdownフォーマットで、API仕様書を作成することができますが、Docusaurusは専用なツールではないため、API仕様書を作成する中で、たくさんの課題もあります。
1. APIリファレンスへの特化が足りない
Docusaurusはマークダウン形式でコンテンツを記述するため、APIリファレンスに特化した構造化されたデータ形式がありません。各APIエンドポイント、パラメータ、レスポンスなどを手作業で記述する必要があり、構造化が難しくなります。
2. API仕様との連携がない
Docusaurusには、API定義ファイル(OpenAPI、Swagger、RAML等)からドキュメントを自動生成する機能がありません。API仕様書とAPIの実装が別々に管理されるため、整合性を保つのが困難になります。
3. バージョン管理の課題
Docusaurusには、APIのバージョン管理機能がないため、複数バージョンのAPIドキュメントを管理するのが難しくなります。各バージョンのドキュメントを個別に作成・管理する必要があります。
4. APIリクエスト機能の統合が難しい
DocusaurusにはネイティブでAPIリクエストを送信する機能がありません。外部ツールやライブラリを統合する必要があり、実装が複雑になる可能性があります。
5. 様々なコードサンプルの記載が難しい
Docusaurusはマークダウン形式のため、さまざまな言語のコードサンプルを適切にハイライトしたり、インタラクティブにレンダリングしたりするのが難しくなります。コードサンプルの記述方法に制限があり、APIの利用例を分かりやすく示すことが困難になる可能性があります。
これらの課題を解決するためには、API仕様書専用のツールやフレームワークを利用することをお勧めします。Apidogは、Docusaurusと同じようにMarkdownファイルを管理したり、Webページに自動変換したりできますし、API定義ファイルから直接ドキュメントを生成でき、バージョン管理、リクエスト機能、コードサンプルの表示など、API仕様書作成に特化した機能も提供されています。
shimizu chioka
Docusaurus代替：ApidogでAPI仕様書を作る
Apidogは、様々なMarkdown記法にも対応でき、MarkdownファイルをDocusaurusのように自動的にWebページに変換することができます。
ApidogのMarkdownについて：https://markdown-jp.apidog.io/
その上、APIスペックファイルから綺麗なAPIドキュメンテーションを生成することができますので、Markdown形式のWebページとAPIドキュメンテーションページを一緒にリストすることが可能です。
API仕様をインポート
Apidogを開くと、APIスペックを直接にApidogにインポートできます。Apidogは、次のように、OpenAPI・Swagger仕様、Postman、Insomniaなど、様々なフォーマットをサポートできます。
API仕様を変更
API仕様ファイルをApidogにインポートすると、Apidogの直感的なUIを用いて、API仕様を変更したりすることも可能です。
API仕様書を生成して公開
API仕様の変更が終わった場合、API仕様書を公開することで、API仕様書が自動的に生成されます。左側メニューから「共有」→「公開設定」の順にクリックして、公開設定を行います。
- カスタムドメインの利用：Apidogを利用して、API仕様書を自分のドメインにデプロイすることが可能です。「カスタムドメイン」の編集ボタンをクリックして、当該ドメインの所有権認証を通すと、API仕様書を指定のドメインにデプロイすることが可能です。
公開済みのAPI仕様書にアクセス
ApidogでAPI仕様書を公開すると、自分で定義したドメインにアクセスして、仕様書を確認することができます。ここでAPI仕様が直感的なAPI仕様書に自動的に変換されます。
API仕様書のサンプル
次のサンプルをご覧ください。Apidogは、API仕様に基づいて非常に綺麗なAPI仕様書を生成することができます。
生成されたAPI仕様書のページでは、次のコンテンツが含まれています：
- エンドポイントの詳細な説明
- 内蔵のAPIリクエスト送信機能
- リクエストパラメータとサンプル
- 様々なフレームワークでのAPIリクエストコードのサンプル
- レスポンスコードごとのケース(200、400、404など)
- レスポンスデータ構造とサンプル
まとめ
Docusaurusは優れた静的サイトジェネレーターですが、API仕様書を作成する際には課題があります。Markdownベースでドキュメントを作成するため、構造化されたAPIリファレンスの作成が難しく、API仕様との連携やバージョン管理、APIリクエスト機能の統合、さまざまなコード例の表示にも制限があります。
一方で、ApidogはAPI仕様書作成に特化したツールです。API定義ファイルからドキュメントを自動生成でき、直感的なUIでAPI仕様の編集も可能です。生成されたAPI仕様書には、エンドポイントの詳細な説明、内蔵のリクエスト機能、パラメータやレスポンスのサンプル、さまざまな言語のコード例が含まれます。
また、カスタムドメインへのデプロイもでき、Markdownベースのコンテンツも一緒に公開できます。 API開発チームは、ApidogとDocusaurusを組み合わせて利用することで、包括的な技術ドキュメントとAPIリファレンスを効率的に作成・公開できます。Apidogを活用することで、APIの変更に合わせてドキュメントを常に最新の状態に保ち、開発者以外の関係者も簡単にAPI仕様を確認できるようになります。
