演習 - XML のコメントと注釈を使用して OpenAPI ドキュメントをカスタマイズおよび拡張する
この演習では、コードにコメントと注釈を追加することで、開発者があなたの API に関して確認するドキュメントを充実させます。 最初に、Swagger UI の既定の結果を見てみましょう。
Swagger UI で API のエンドポイントの OpenAPI 定義を確認するには、ブラウザーで
http://localhost:5000/swaggerに移動します。 Get メソッドを選択すると、次のような出力が表示されます。
Swagger UI では、API に関していくつかの役に立つ情報が提供されます。 呼び出すことができるメソッド (この簡単な例では、PriceFrame という名前の 1 つのメソッド) が示されます。 それが Height と Width という名前の 2 つの必須パラメーターを受け取る HTTP Get 操作であることが確認できます。 API 呼び出しのアクションを確認するには、[試してみる] を選択し、[Height] と [Width] の値を入力してから、[実行] を選択します。
API ユーザーにはまだ、PriceFrame メソッドの制限事項を知るのに十分な情報がありません。 XML コメントを使って、さらにいくつか詳細な情報がわかるようにしてみましょう。
XML コメントを API に追加する
前回の演習で使用した Visual Studio Code のインスタンスに戻ります。
最後の演習の Web API がまだ実行中である場合、Windows では ctrl+c キー、Mac では cmd+c キーを押して、それを停止します。
プロジェクトで XML ドキュメントをアクティブにするには、PrintFramerAPI.csproj プロジェクト ファイルを更新し、
GenerateDocumentationFileタグを既存の<PropertyGroup>に追加し、それをtrueに設定します。<PropertyGroup> <TargetFramework>net7.0</TargetFramework> <GenerateDocumentationFile>true</GenerateDocumentationFile> <NoWarn>$(NoWarn);1591</NoWarn> </PropertyGroup>Startup.cs で、次の using ステートメントを追加します。
using System.Reflection; using System.IO;Startup.cs で、
ConfigureServices内でのAddSwaggerGen()の呼び出しを更新することで、XML ドキュメントを使用するように Swashbuckle に指示します。public void ConfigureServices(IServiceCollection services) { services.AddControllers(); // Register the Swagger generator, defining 1 or more Swagger documents services.AddSwaggerGen(c => { c.SwaggerDoc("v1", new OpenApiInfo { Version = "v1", Title = "PrintFramer API", Description = "Calculates the cost of a picture frame based on its dimensions.", TermsOfService = new Uri("https://go.microsoft.com/fwlink/?LinkID=206977"), Contact = new OpenApiContact { Name = "Your name", Email = string.Empty, Url = new Uri("https://learn.microsoft.com/training") } }); // Set the comments path for the Swagger JSON and UI. var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml"; var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile); c.IncludeXmlComments(xmlPath); }); }上のコードでは、リフレクションによって、XML コメントを読み込む XML ファイルの名前を決定しています。
Controllers フォルダーで、PriceFrameController.cs を開きます。
GetPriceメソッドの HttpGet 属性の上に、次の XML コメント ブロックを追加します。 スラッシュ 3 個のコメントをアクションに追加し、セクション ヘッダーに説明を追加することで、Swagger UI の情報量を増やします。/// <summary> /// Returns the price of a frame based on its dimensions. /// </summary> /// <param name="Height">The height of the frame.</param> /// <param name="Width">The width of the frame.</param> /// <returns>The price, in dollars, of the picture frame.</returns> /// <remarks> The API returns 'not valid' if the total length of frame material needed (the perimeter of the frame) is less than 20 inches and greater than 1000 inches.</remarks> [HttpGet("{Height}/{Width}")] public string GetPrice(string Height, string Width) { string result; result = CalculatePrice(Double.Parse(Height), Double.Parse(Width)); return $"The cost of a {Height}x{Width} frame is ${result}"; }すべての変更を保存し、ローカルでビルドされるようにするには、Visual Studio Code ターミナル ウィンドウで次のコマンドを実行します。
dotnet build変更を確認するには、Visual Studio Code ターミナル ウィンドウで次を入力して、ASP.NET アプリケーションをローカルで実行します。
dotnet runhttp://localhost:5000/swaggerで Swagger UI をもう一度調べて、XML コメントで提供した情報が OpenAPI ドキュメントに追加されていることを確認します。
データ注釈を API に追加する
Swagger で OpenAPI ドキュメントを改良できるようにするには、Microsoft.AspNetCore.Mvc 名前空間の属性を使用します。
最後の演習の Web API がまだ実行中である場合、Windows では ctrl+c キー、Mac では cmd+c キーを押して、それを停止します。
GetPriceAPI で text/plain に対するコンテンツ タイプ応答がサポートされていることを示すには、API コントローラー PriceFrameController.cs で、GetPrice定義の上に、[Produces("text/plain")]属性を追加します。[HttpGet("{Height}/{Width}")] [Produces("text/plain")][Response Content Type]\(応答コンテンツ タイプ\) ドロップダウンでは、コントローラーの GET アクションに対する既定値として、このコンテンツ タイプが選択されています。
Swashbuckle の注釈を API に追加する
現状、API は、与えられたフレーム寸法の価格を計算できる場合、状態コード 200 を返します。 GetPrice メソッドの説明で、価格を計算できないケースについて言及します。
より確実に応答の種類とエラー コードを開発者に伝える方法は、次の XML コメントとデータ注釈を使用することです。 Swashbuckle と Swagger ツールは、これらの値を使用して、予期される HTTP 応答コードの OpenAPI 記述を明確に生成します。
また、Name プロパティを含めるように HTTP 動詞フィルター コンストラクターを更新し、OpenAPI の operationId 値を含めます。
PriceFrameController.cs ファイルに次の using ステートメントを追加します。
using Microsoft.AspNetCore.Http;PriceFrameController.cs で、
GetPriceを次のコードとコメントに置き換えます。/// <summary> /// Returns the price of a frame based on its dimensions. /// </summary> /// <param name="Height">The height of the frame.</param> /// <param name="Width">The width of the frame.</param> /// <returns>The price, in dollars, of the picture frame.</returns> /// <remarks> /// Sample request: /// /// Get /api/priceframe/5/10 /// /// </remarks> /// <response code="200">Returns the cost of the frame in dollars.</response> /// <response code="400">If the amount of frame material needed is less than 20 inches or greater than 1000 inches.</response> [HttpGet("{Height}/{Width}", Name=nameof(GetPrice))] [Produces("text/plain")] [ProducesResponseType(StatusCodes.Status200OK)] [ProducesResponseType(StatusCodes.Status400BadRequest)] public ActionResult<string> GetPrice(string Height, string Width) { string result; result = CalculatePrice(Double.Parse(Height), Double.Parse(Width)); if (result == "not valid") { return BadRequest(result); } else { return Ok($"The cost of a {Height}x{Width} frame is ${result}"); } }このコード更新により、次の変更が行われます。
- メソッドでは、
BadRequest()およびOk()メソッドを使用して、それぞれ BadRequest (400) と OK の状態が作成され、応答に文字列の結果が渡されます。 - XML コメントには、このメソッドから返される各状態コードが記述されています。
- HttpGet 属性には、OpenAPI の
operationIdパラメーターを生成するためのNameプロパティが含まれています。 - ProducesResponseType 属性は、アクションによって返される可能性のあるさまざまな応答をリストアップするものです。 これらの属性と、さきほど説明した XML コメントが組み合わされて、各応答についての人間が理解しやすい説明が、生成される Swagger に追加されます。
- メソッドでは、
次のコマンドを使用して、Web API をリビルドします。
dotnet build次のコマンドを使用して、ASP.NET アプリケーションを実行します。
dotnet runhttp://localhost:5000/swaggerで Swagger UI をもう一度調べて、これらの注釈で提供した情報が追加されていることを確認します。 API の最終的な Swagger UI は次の図のようになります。
この演習では、あなたの API について開発者が受け取る情報を充実させ、いっそう簡単に利用できるようにしました。