ASP.NET CoreでWeb APIを利用するメリット
なぜASP.NET Coreなのか？
ASP.NET CoreにWeb APIが設けられているもう一つの理由は、通常のASP.NET Coreアプリケーションの開発手法とリソースを活用できるからです。Web APIといっても、それはASP.NET Core MVCアプリケーションからビューなどWebサービスでは不要なものを取り去ったものと言えるので、開発手法に大きな違いは出ません。ビューこそ提供しませんが、ルーティング、コントローラ開発、モデル開発、そしてEntity Frameworkといったコンポーネントについても活用が可能です。
Webサービスでは、突き詰めればJSONやXMLといった形式のデータを提供できればいいので、ASP.NET Coreなどのフレームワークを使用しない、極論すればPHPやPythonなどのスクリプトをただ動かすだけのような実装も可能です。しかし、効率的な開発やテスト、それに運用管理も考慮すれば、ASP.NET Coreのようなフレームワーク上に構築した方が多くの恩恵を得られます。例えば、ASP.NET Coreでは以下のような機能が提供され、Web APIでも利用できます。
- 開発、テスト、本番環境の使い分け
- 基本的なセキュリティ機能
- カスタマイズ可能なログ出力
- ルーティング
- キャッシュの利用
- 認証機能
- ジェネレータ機能（Scaffoldingなど）
Web APIの構成
ここまでで、Web APIを利用するメリットを紹介しました。このWeb APIは、.NET 6からは2つのフレームワークを選択して使い分けることができるようになっています。一つは、.NET 6以前から利用可能であったコントローラベースのWeb APIフレームワークです。そしてもう一つは、Minimal APIという文字通り最小限の構成のフレームワークです。
コントローラベースのWeb APIは、ASP.NET Coreの備える機能をフルに生かしたアプリケーション開発が可能なので、ジェネレータ機能を生かしたRESTfulなAPIの実装をはじめとして、さまざまな局面での利用が可能です。これに対してMinimal APIには、コントローラベースのWeb APIに比較して、以下のような制限があります。
- モデルへのバインディングがサポートされない
- フォームからのバインドがサポートされない
- 検証の組み込みがサポートされない
- アプリケーションパーツ（プロジェクト間でアクションなどを共有する仕組み）とアプリケーションモデル（MVCなどのルールの適用）がサポートされない
- 組み込みのビューのレンダリングがサポートされない
- JsonPatch、ODataがサポートされない
特に、モデルへのバインディングが組み込みでサポートされないので、データに対するCRUD処理が必要な場合にはコントローラベースのWeb APIの利用が推奨されます。そうでない場合には、シンプルな構成のMinimal APIを利用すると軽量でコンパクトなWebサービスの構築が可能になります。
Swaggerによるサポート
コントローラベースのWeb API、Minimal APIともに、Swaggerと呼ばれるツールを利用可能です。Swaggerとは、SmartBear Software社によるAPI開発者向けのツールスイートであり、APIの記述についての仕様です。現在では、SwaggerをベースとしたOpenAPI Specification（OAS）が標準となっており、Swaggerといえばツールスイートを指すことが多くなっています。Swaggerは以下のツールから構成されます。
- Swagger Editor……OASを記述するWebベースのエディタ
- Swagger UI……OASをもとにAPIのドキュメントをHTMLで提供
- Swagger Codegen……OASから各言語のコードを生成
Swaggerは同社によるものが本家ですが、オープンソースのツールやライブラリも存在します。Web APIでは、このうちSwashbuckleとNSwagという2つのコンポーネントで実装されています。ルートやコントローラ、モデルからOASを生成したり（Swaggerジェネレータ）、OASをもとにドキュメントや検証用のUIを構築できます（Swagger UI）。これにより、特に検証用のクライアントを用意する必要なく、APIの検証が実施できるようになっています。これも、ASP.NET Core Web APIを利用するメリットの一つと言えます。
［NOTE］OpenAPI Specification（OAS）とは
OpenAPI Specification（OAS）とは、Web APIのインタフェース定義を定めた標準です。APIの仕様について、エンドポイントとその操作、パラメータやレスポンス、認証についてJSON形式などで記述することができます。OASとして標準化されるまでは、Swagger仕様と呼ばれていました。OASにより、開発者間はもとよりプログラムコードともAPIの仕様を共有するのが容易になります。具体的な内容の例を図2に示します。これは、後述する実行例においてリンクとして表示されているものです。表示される内容には、APIの仕様が細かく記述されています。
