API ドキュメントを作成する
ソース コード リポジトリの API を文書化することは、API を保守および使用する開発者に明確さ、アクセシビリティ、使いやすさを提供するために不可欠です。 包括的なドキュメントは、API エンドポイントの機能、入力、出力、使用方法を理解するためのガイドとして役立ちます。 API を文書化する場合、例や使用シナリオなどを含む最も適切な提示形式 (OpenAPI 仕様や Markdown など) を選択し、それをコードの変更に合わせて最新の状態に保ち、API コンシューマーにフィードバックを求めて品質を継続的に向上する必要があります。
API を文書化する一般的なアプローチはプラットフォームに依存しませんが、Azure DevOps と GitHub では実装にいくつかの違いがあります。
Azure DevOps で API を文書化する
最も効率的な方法で API ドキュメントを Azure DevOps プロジェクトに追加するには、開発ワークフローと統合される専用のドキュメント ツールまたはプラットフォームの利用を検討する必要があります。 このカテゴリの人気のある選択肢としては、Swagger (OpenAPI)、API Blueprint、Markdown ベースのドキュメント システム (MkDocs や Docusaurus など) などがあります。 それらの Azure DevOps 統合機能は、生成ドキュメントのプロセスを自動化し、コードベースとの同期を維持するのに役立ちます。 ほとんどのドキュメント ツールでは、インライン コメントの解析と、自動生成されたドキュメントへのそれらの包含もサポートされています。
API ドキュメントは、チーム メンバーと関係者がアクセスできる中央の場所に発行する必要があります。 これは、専用のドキュメント Web サイト、Azure DevOps 内の Wiki、または外部のドキュメント ポータルになります。
または、コード内でコード注釈またはデコレーターを直接使用して、API エンドポイントを記述するメタデータを追加することもできます。 Swagger Codegen や Springfox などのツールは、これらの注釈を処理し、OpenAI 仕様のファイルを生成できます。
コードベースが変更されるたびに API ドキュメントを自動的に生成するように、Azure Pipelines 内で自動化されたプロセスを設定します。 これにより、ドキュメントは最新の状態に保たれ、API の最新の変更を反映します。
GitHub での API の文書化
GitHub を使用する場合は、GitHub エコシステムの一部であるツールを利用して API ドキュメントを生成することを検討します。
まず、API エンドポイント、操作、パラメーター、応答、その他の関連情報を文書化します。 幅広いサポートと使いやすさを考慮して、そのドキュメントを Markdown 形式で作成することを検討します。 個々のドキュメントの一貫した構造を定義し、それぞれを認証、エンドポイント、要求パラメーター、応答例などを説明するセクションに分割します。
Azure DevOps と同様に、ドキュメント ジェネレーターまたは静的サイト ジェネレーターを使用して、Markdown ファイルから API ドキュメントを生成するプロセスを効率化できます。 人気のある選択肢としては、Jekyll、MkDocs、Docusaurus、Hugo があります。 Markdown ファイルを解析し、静的 HTML ページを生成するようにジェネレーターを構成します。 プロジェクトのブランド化や好みに合わせて、レイアウト、テーマ、スタイルをカスタマイズできます。
HTML コンテンツを公開するには、GitHub リポジトリから直接静的な Web サイトをホストできる GitHub Pages を利用します。 この目的のために専用のブランチを作成し、このブランチに HTML ファイルをプッシュすることができます。 また、GitHub Actions を実装して、ドキュメント ファイルまたはコードベースが変更されるたびに API ドキュメントを自動的にビルドしてデプロイすることもできます。
ドキュメント ファイルまたはコードベースで変更が発生するたびに、API ドキュメントを自動的にビルドしてデプロイするように GitHub Actions を設定します。 選択したドキュメント ジェネレーターを使用して HTML ドキュメント ファイルを生成し、それらを GitHub Pages にデプロイするように自動化ワークフローを構成します。