API ドキュメントを作成する

ソース コード リポジトリの API ドキュメントを作成することは非常に重要です。 優れたドキュメントは、開発者が API を簡単に理解し、維持し、使用するのに役立ちます。 完全なドキュメントでは、API のしくみ、必要な入力、提供される出力、および API エンドポイントの使用方法について説明します。 API ドキュメントを作成する場合は、最適な形式 (OpenAPI 仕様や Markdown など) を選択し、例や使用シナリオを含め、コードが変更されたときに更新を維持し、API ユーザーにフィードバックを求めて改善する必要があります。 API ドキュメントに対する一般的なアプローチはどこでも機能しますが、Azure DevOps と GitHub にはいくつかの違いがあります。

Azure DevOps での API ドキュメントの作成

Azure DevOps プロジェクトに API ドキュメントを効率的に追加するには、開発ワークフローで動作する専用のドキュメント ツールを使用する必要があります。 一般的な選択肢には、Swagger (OpenAPI)、API Blueprint、MkDocs や Docusaurus などの Markdown ベースのドキュメント システムがあります。 Azure DevOps 統合は、ドキュメントの作成を自動化し、コードとの同期を維持するのに役立ちます。 ほとんどのドキュメント ツールでは、インライン コメントを読み取り、自動的に生成されたドキュメントに含めることもできます。

API ドキュメントは、チーム メンバーと関係者がアクセスできる中央の場所に発行する必要があります。 これは、専用のドキュメント Web サイト、Azure DevOps 内の Wiki、または外部ドキュメント ポータルです。

コードの注釈またはデコレーターをコード内で直接使用して、API エンドポイントを記述するメタデータを追加することもできます。 Swagger Codegen や Springfox などのツールでは、これらの注釈を処理し、OpenAPI 仕様ファイルを作成できます。

コードが変更されるたびに API ドキュメントを自動的に作成するように、Azure Pipelines 内で自動化されたプロセスを設定します。 これにより、ドキュメントが最新の状態に保たれ、API の最新の変更が反映されます。

GitHub での API ドキュメントの作成

GitHub を使用する場合は、GitHub エコシステムの一部であるツールを使用して API ドキュメントを作成することを検討してください。

まず、API エンドポイント、操作、パラメーター、応答、およびその他の関連情報を文書化します。 このドキュメントは広くサポートされており、使いやすいため、Markdown 形式で作成することを検討してください。 個々のドキュメントの一貫性のある構造を定義し、認証、エンドポイント、要求パラメーター、応答の例などを説明するセクションに分割します。

Azure DevOps と同様に、ドキュメント ジェネレーターまたは静的サイト ジェネレーターを使用して、Markdown ファイルから API ドキュメントを簡単に作成できます。 人気のある選択肢は、Jekyll、MkDocs、Docusaurus、Hugo です。 Markdown ファイルを読み取り、静的 HTML ページを作成するようにジェネレーターを設定します。 プロジェクトのブランドと設定に合わせて、レイアウト、テーマ、スタイルをカスタマイズできます。

HTML コンテンツを発行するには、GitHub Pages を使用します。GitHub ページを使用すると、GitHub リポジトリから直接静的な Web サイトをホストできます。 この目的のために専用のブランチを作成し、HTML ファイルをこのブランチにプッシュできます。 GitHub Actions を使用して、ドキュメント ファイルまたはコードが変更されるたびに API ドキュメントを自動的にビルドしてデプロイすることもできます。

ドキュメント ファイルまたはコードが変更されるたびに API ドキュメントを自動的にビルドおよびデプロイするように GitHub Actions を設定します。 選択したドキュメント ジェネレーターを使用して HTML ドキュメント ファイルを作成し、GitHub Pages にデプロイするように自動化ワークフローを構成します。