Swagger ツールを使用して ASP.NET Core Web API を文書化する
API には大きな価値がありますが、開発者がその使い方を理解していないと役に立ちません。 開発者は、できる限りすばやく API を統合できることを望みます。 適切な API ドキュメントによって、開発者が API の機能と使用方法を理解するのに役立ち、より効率的に統合できるようになります。
従来、API とその使用方法を説明するすべてのドキュメントは、手作業で記述されていました。 現在、API の記述については、OpenAPI と呼ばれる標準仕様があります。 Swagger UI には、API の OpenAPI 仕様の実装とテスト ツールが用意されています。 Swashbuckle は、.NET リフレクションを使用して、Web API コントローラーから直接 OpenAPI 記述ドキュメントの自動生成を提供するオープンソース パッケージです。 Swashbuckle は、記述プロセスを自動化して、チームが OpenAPI ベースの API ドキュメントを簡単に生成、管理、および使用するのに役立ちます。 API を記述したら、ツールで充実したドキュメントを生成できます。
OpenAPI とは
OpenAPI は、REST API を記述するために使用される仕様です。 それは言語に依存せず、次のものを含む API 全体を記述できます。
- 使用可能なエンドポイント
- 操作のパラメーター
- 認証方法
- 連絡先とその他の情報
YAML または JSON で API の仕様を記述できます。 OpenAPI の仕様では、人間もコンピューターも、ソース コードにアクセスすることなく、API の機能を理解できます。
Swagger とは
Swagger は、OpenAPI 仕様を中心に構築された一連のオープンソース ツールです。 これらのツールを利用して、REST API の設計、構築、文書化を行うことができます。 Swagger は、API の OpenAPI 仕様を使って、その構造を理解します。
たとえば、Swagger UI は、OpenAPI 仕様で定義されている API のドキュメントをブラウザーで視覚的にレンダリングできるツールです。 Swagger Codegen は、API の同じ OpenAPI 仕様を取得して、クライアント SDK を生成できます。
Swashbuckle とは
Swashbuckle は、.NET リフレクションを使用して、.NET Core API 用の Swagger ドキュメントを生成するために使用されるオープンソースの Swagger の実装です。
Swashbuckle には 3 つの主要なコンポーネントがあります。
Swashbuckle.AspNetCore.Swagger: このコンポーネントは、JSON エンドポイントとして
SwaggerDocumentオブジェクトを公開する Swagger のオブジェクト モデルとミドルウェアです。Swashbuckle.AspNetCore.SwaggerGen: このライブラリは、ルート、コントローラー、モデルから
SwaggerDocumentオブジェクトを直接構築する Swagger ジェネレーターです。 ライブラリは、通常、Swagger エンドポイント ミドルウェアと組み合わされて、Swagger JSON を自動的に公開します。Swashbuckle.AspNetCore.SwaggerUI: このパッケージは、Swagger UI ツールの埋め込みバージョンです。 Swagger JSON を解釈し、Web API の機能を記述するためのリッチでカスタマイズ可能なエクスペリエンスを構築します。 これには、パブリック メソッド用の組み込みのテスト ハーネスが含まれます。
Swashbuckle CLI: この .NET グローバル ツールをインストールすると、ビルドまたは発行時に OpenAPI 仕様を生成できるようになります。 このモジュールの最後に、Swashbuckle CLI をダウンロードするためのリンクがあります。
これらのライブラリはアプリに追加され、最新バージョンの API から API のドキュメントを生成して視覚化します。 これらは、最新のコードと常に同期された "生きている" ドキュメントを作成します。