.NET 9 APIでSwaggerを置き換える4つの選択肢

.NET 9の正式リリースに伴い、MicrosoftはデフォルトのWeb APIテンプレートでSwagger UIのビルトインサポートを削除しました。 一部のコミュニティメンバーはこのシフトに懸念を表明したが、Tim Corey氏は彼のビデオ"4 Options to Replace Swagger in .NET 9 APIs"で、この変更は実際に開発者により柔軟性を与え、コードとツールの間の分離をすっきりさせると説明している。

この記事では、.NET 9でOpenAPIドキュメントを生成するためのSwagger UIに代わる4つの主要な選択肢を、Timのハンズオンビデオのウォークスルーに基づいて紹介します。 既存のプロジェクトをアップグレードしようとしていたり、最小限のAPIで新たに始めようとしている場合、このガイドは、利用可能なツールと、それらがどのようにOpenAPI標準をサポートしているかを理解するのに役立ちます。

標準 API プロジェクトのセットアップ

Tim氏はまず、Visual Studioで最小限のAPIプロジェクトを作成し、標準のASP.NET Core Web APIテンプレートを選択します。

彼は、OpenAPIサポートを追加するボックスにチェックを入れることを強調しています。これは、プロジェクトがJSONファイルのエンドポイントを介して必要なOpenAPIドキュメント生成を含むことを保証するものです。

プロジェクトが実行されると、TimはデフォルトのOpenAPIドキュメントURL（例：/swagger/v1/swagger.json）にナビゲートし、生のOpenAPI仕様を表示します。 このファイルには、GET、POST、DELETEなどのサポートされている動詞を含む、APIエンドポイントに関する構造化されたメタデータが含まれています。

機能的ではあるが、ティムは、生のOpenAPIドキュメントの閲覧はユーザーフレンドリーではないと指摘する。 より良いウェブベースのドキュメンテーション・インターフェースを提供するために、彼は、開発者と消費者の体験を向上させる4つの外部ツールのデモンストレーションに進む。

オプション1: Swagger UI - おなじみのエクスペリエンス

Swagger UIは、もはやデフォルトでは含まれていませんが、今でも非常に人気のあるツールです。 Tim は必要な NuGet パッケージ .NET: Swashbuckle.AspNetCore.SwaggerUI を使用してそれを戻す方法を示しています。

新しいプロジェクトでSwagger UIをセットアップした後、9:43に、簡略化された構文を使用してミドルウェアを設定し、起動URLを/swaggerに設定する。 このUIは、開発者がエンドポイントを表示し、リクエストパラメータを理解し、ブラウザ内でテストすることができるユーザーフレンドリーなAPIドキュメントインターフェイスを提供します。

Swagger UIは現在、外部ツールですが、OpenAPI仕様をサポートしており、開発中の基本的なドキュメンテーションのニーズに最適な選択肢の1つです。

オプション2: ReDoc - クリーンで読み取り専用のAPIドキュメント

ティムの2つ目のツールはReDocで、これはOpenAPIドキュメントを洗練された、読み取り専用のHTMLサイトに変換します。OpenAPIパッケージ Swashbuckle.AspNetCore.ReDoc を追加した後、彼はドキュメントを /api/docs にマップします。

Swagger UIとは異なり、ReDocではエンドポイントのテストはできません。 しかし、外部ユーザーやクライアントに適したウェブベースのドキュメント・インターフェースとして輝きを放ちます。 純粋にREST APIを定義し、構造化されたドキュメントを表示することに重点を置いている場合、ReDocは最適です。

ReDocは、提供されたOpenAPI仕様に基づいてコンテンツを自動的に生成し、期待されるレスポンス、パラメータ、データタイプをカバーすることは注目に値します。これは、インタラクティブ性よりも、ドキュメンテーションのための最適化されたビルトインサポートを優先するプロジェクトとうまく調和します。

オプション3: NSwag - ドキュメンテーション + コード生成

Timは次に、柔軟で機能豊富なツールであるNSwagについて説明します。NSwagは、単にAPIを文書化するだけでなく、C#、TypeScriptなどさまざまな言語でクライアントのコードを生成することができます。 NSwag.AspNetCoreのNuGetパッケージをインストールした後、彼はSwaggerのようなインターフェースをセットアップし、同じJSONエンドポイントにマッピングする。

ティム氏は、NSwagはSwagger仕様とOpenAPI標準の両方をサポートしており、開発者は好みのフォーマットを選択できると説明する。 UIはSwaggerに似ているかもしれませんが、NSwagを輝かせるのは外部ツールライブラリと高度な機能（自動クライアント作成など）です。

NSwagのコード生成機能は、特に複数のサービスや外部ツールを含むプロジェクトで、APIと統合する際の手作業を減らすのに役立つと指摘する。 これは、堅牢なクライアントサーバー通信を構築するチームのための強力なソリューションです。

オプション4: Scaler - APIテストのためのティムのお気に入り

ティムは、Scaler UIをあらゆる選択肢の中で個人的に最も気に入っているものとして紹介し、Postmanとブラウザでのドキュメンテーションを融合させたものだと説明する。 Scaler.AspNetCoreパッケージを追加した後、インターフェースを有効にするために必要なコードは1行（app.MapScalerApiReference()）だけです。

Scalerは、クエリパラメータ、ヘッダー、クッキーを含むリクエストの実行など、完全なインタラクティブ性をサポートしています。 このツールの特徴は、応答時間、ヘッダー、結果のペイロードを即座に返すリアルタイムのフィードバックです。

Scalerの際立った特徴は、さまざまな言語（PHP、Node、Python、HttpClientとRestSharp経由のC#）用のcurlコマンドとクライアントコードのスニペットを生成する機能です。 ティムは、開発中にAPIコールをすばやくコピー＆ペーストするために、このツールが特に有用であることを実感しています。

Scalerは、ライトモードとダークモードの切り替えも可能で、ユーザーフレンドリーなAPIドキュメンテーションプラットフォームです。 オープンソースのAPIプラットフォームとして、Scalerは積極的なメンテナンスとコミュニティの強い関心によって進化し続けています。

最後に思うこと：オプションは柔軟性をもたらす

ビデオの最後の数分で、Timは.NETウェブテンプレートからSwagger UIを削除することは、一歩後退したように見えるかもしれないが、実際には最新の、よりカスタマイズされたソリューションを採用する機会であると強調している。 この変更は、機能がよりモジュール化され、焦点が絞られてきているマイクロソフトの高速リリースサイクルに沿ったものです。

OpenAPIサポートは、現在、厳格なネイティブ実装というよりも、第一級市民サポートとして機能しています。 Scalerを使ったインタラクティブなテスト、NSwagを使ったクライアントコード生成、ReDocを使ったクリーンな出力など、プロジェクトのニーズに応じて自由にツールを組み合わせてください。

Timは、開発者がこれらのツールを探索し、どれが自分のワークフローに合うかを確認し、場合によっては、異なる環境（たとえば、1つは開発用、もう1つは公開ドキュメント用）に複数のUIを使用することも奨励します。 これらのオプションはすべてOpenAPIとSwagger仕様に対応しているため、単一のベンダーやワークフローに縛られることはありません。

結論

.NET 9でデフォルトのSwagger UIが削除されたおかげで、開発者はOpenAPIドキュメンテーションのニーズに最適なツールを自由に選択できるようになりました。 HTTP API の文書化、外部ツールの提供、内部開発のサポートなど、お客様の目標に合ったソリューションがあります。

Swagger UI、ReDoc、NSwag、Scalerなどのツールにより、APIのドキュメント化とテストはかつてないほどカスタマイズしやすく、開発者フレンドリーになっています。 ティム・コーリーがビデオで紹介しているように、必要なのは、いくつかのパッケージ、数行のコード、そして、アプリケーションとチームに最適なツールを探求する意欲だけです。