Visual Studio 2022 のテンプレートを使ってターゲットフレームワーク .NET 8.0 で ASP.NET Core Web API のプロジェクトを作成し、Visual Studio から実行すると下の画像のようにブラウザ上に swagger/index.html というページが表示され、そこから Web API のアクションメソッドを要求して応答を調べることができます。（追記: 2024/11/25 時点で、ターゲットフレームワーク .NET 9.0 で作成した Web API プロジェクトには Swagger は含まれません）

Swagger を使って、(1) ファイルをアップロードする方法、及び (2) ベアラトークンを要求ヘッダに含めて送信する方法を調べましたので、備忘録として残しておくことにしました。

先の記事「ASP.NET Core Web API と Swagger（その１）」では (1) について書きました。この記事では (2) について書きます。

(2) ベアラトークンを要求ヘッダに含める

これについてはネットで検索して見つけた記事 OAuth Bearer Token with Swagger UI — .NET 6.0 が参考になりました。

テンプレートを使って作った ASP.NET Core Web API のプロジェクトの Program.cs に含まれている AddSwaggerGen メソッドを以下のように拡張します。コードに Use baerer token authorization header とコメントしてありますように、Type に SecuritySchemeType.Http を設定するのがポイントです。

//builder.Services.AddSwaggerGen();

builder.Services.AddSwaggerGen(options =>
{
    options.SwaggerDoc("v1", new OpenApiInfo 
    { 
        Title = "My Web API", 
        Version = "v1" 
    });

    options.AddSecurityDefinition("Bearer", new OpenApiSecurityScheme
    {
        Name = "Authorization",

        // Use baerer token authorization header
        Type = SecuritySchemeType.Http,

        Scheme = "Bearer",
        BearerFormat = "JWT",
        In = ParameterLocation.Header,
        Description = "Please enter token",
    });

    options.AddSecurityRequirement(new OpenApiSecurityRequirement
    {
        {
            new OpenApiSecurityScheme
            {
                Reference = new OpenApiReference
                {
                    Type = ReferenceType.SecurityScheme,
                    Id = "Bearer"
                }
            },
            new List<string>()
        }
    });
});

上の OpenApiSecurityRequirement クラスの初期化のコードが見慣れない形になっていますが、それについて説明しておきます。

OpenApiSecurityRequirement クラスは Dictionary<OpenApiSecurityScheme,IList<String>> を継承してます。なので、コレクション初期化子を使用してディクショナリを初期化するのと同様に new Dictionary<TKey, TValue> {{ key1, value 1}, { key2, value2 }} という形でキーと値のペアを Add しながら OpenApiSecurityRequirement クラスを初期化しています。

上のコードを実装すると、この記事の一番上の画像のように、ブラウザに表示される Swagger 画面の右上に赤枠で囲ったように［Authorize］ボタンが表示されるようになります。

それをクリックすると、下の画像のように Available authorizations ダイアログがポップアップ表示されるので、そのテキストボックスにトークンを入力して、ダイアログ上の［Authorize］ボタンをクリックすれば、以降は Swagger からの要求すべてにベアラトークンが要求ヘッダに含まれて送信されるようになります。

下は Swagger からの要求を Fiddler でキャプチャした画像です。赤枠で示したように要求ヘッダにベアラトークンが含まれて送信されています。

上の操作で設定したベアラトークンを送信しないようにするには、Swagger 画面右上の［Authorize］ボタンをクリックして Available authorizations ダイアログを表示し、［Logout］ボタンをクリックします。

Visual Studio 2022 のテンプレートを使ってターゲットフレームワーク .NET 8.0 で ASP.NET Core Web API のプロジェクトを作成し、Visual Studio から実行すると下の画像のようにブラウザ上に swagger/index.html というページが表示され、そこから Web API のアクションメソッドを要求して応答を調べることができます。（追記: 2024/11/25 時点で、ターゲットフレームワーク .NET 9.0 で作成した Web API プロジェクトには Swagger は含まれません）

Swagger を使って (1) ファイルをアップロードする方法、及び (2) ベアラトークンを要求ヘッダに含めて送信する方法を調べましたので、備忘録として残しておくことにしました。

(1) と (2) を一つの記事に書くと長くなりすぎるので、この記事では (1) を書いて、(2) は別の記事に「その２」として書くことにします。

(1) ファイルアップロード

アクションメソッドの引数に IFormFile 型の変数を含めれば、Swagger が自動的にそれを検出してアップロードするファイルの選択が可能になり、Swagger から Web API にファイルをアップロードできるようになります。

Swagger にファイル選択のための画面を表示するには、まず、［Try it out］ボタンをクリックします。

［Try it out］ボタンをクリックすると、下のように、ブラウザが html の <input type="file" > を表示した時と同様なファイル選択を行うための画面が表示されます。

その画面でアップロードするファイルを選択したら、［Execute］ボタンをクリックすれば選択したファイルは multipart/form-data 形式でサーバーに送信され、アクションメソッドの引数に渡されます。

下の Fiddler による要求のキャプチャ画像を見てください。

アクションメソッドへの引数に IFormFile 型の変数を含める方法ですが、下のコード例の SampleA メソッドのように直接含めても、SampleB メソッドのようにモデル経由で含めても、Swagger が自動的にそれを検出してくれます。上の画像は SampleA のものですが、SampleB でも同様になります。

using Microsoft.AspNetCore.Mvc;

namespace WebApi2.Controllers
{
    [Route("[controller]")]
    [ApiController]
    public class UploadController : ControllerBase
    {
        [HttpPost("SampleA")]
        public IActionResult SampleA(IFormFile? postedFile, 
                                     [FromForm] string? customField)
        {
            if (postedFile == null || postedFile.Length == 0)
            {
                return Content("ファイルを受信できませんでした");
            }

            if (customField == null)
            {
                return Content("customField を受信できませんでした");
            }

            return Content($"ファイル: {postedFile.FileName}, " +
                $"customField: {customField} 受信");
        }

        [HttpPost("SampleB")]
        public IActionResult SampleB([FromForm] UploadModels model)
        {
            if (model.PostedFile == null || model.PostedFile.Length == 0)
            {
                return Content("ファイルを受信できませんでした");
            }

            if (model.CustomField == null)
            {
                return Content("customField を受信できませんでした");
            }

            return Content($"ファイル: {model.PostedFile.FileName}, " +
                $"customField: {model.CustomField} 受信");
        }
    }

    public class UploadModels
    {
        public string? CustomField { get; set; }
        public IFormFile? PostedFile { get; set; }
    }
}

この記事の本題とは関係ない話ですが、上のサンプルコードで、SampleA の引数の型、SampleB が使う UploadModels のプロパティの型が null 許容型となっているのには理由がありますのでそれも書いておきます。

ユーザーがファイルを選択しないまま / customFiled が空白のまま［Execute］ボタンをクリックすると、null をアクションメソッドの引数にバインドしようとします。なので、引数を null 許容型にしておかないと、バインド時にエラーとなって HTTP 400 Bad Request が応答として返され、アクションメソッドは実行されません。

上のコード例で言うと、if 文以下は実行されないので期待した応答（"customField を受信できませんでした" とか "ファイルを受信できませんでした"）は返ってこないということになります。

Fiddler は、ブラウザなどの HTTP 通信を行うアプリケーションと Internet / Intranet の間の要求・応答をキャプチャして表示してくれる、Web アプリ開発には欠かせないツールです。（注: この記事は Windows OS 専用の Fiddler Classic の話です）

HTTPS 通信もキャプチャ・復号して内容を表示してくれますが、そのために Fiddler は、Fiddler とクライアントの間に独自のサーバー証明書を利用します。

下の画像で赤枠で囲った DO_NOT_TRUST_FiddlerRoot がそれで、Fiddler のオプション設定によって「信頼されたルート証明機関」にインストールされます。

証明書 NOT_TRUST_FiddlerRoot には有効期限があります。自動的には更新してくれないので、忘れた頃に突然証明書が無効だというエラーが出て焦ることになると思います。

下の画像がそれで、Fiddler を起動して、Visual Studio で起動した Web アプリを Chrome から呼び出して表示しようとしたら NOT_TRUST_FiddlerRoot の有効期限切れでエラーになったというものです。

上の画像の NET::ERR_CERT_DATE_INVALID をクリックすると Subject:localhost 以下の詳細情報が表示されますので、その中の Issuer でどの証明書に問題があるのかが分かります。

（ちなみに、Fiddler と Web サーバーの間は別の証明書を使っており、それが開発用の証明書の場合は有効期限が切れることがままあって、その場合は Issuer が上の画像の DO_NOT_TRUST_FiddlerRoot とは異なるので分かります）

NOT_TRUST_FiddlerRoot の有効期限を延長するにはどうするかと言うと、Fiddler のツールバーの [Tools] ⇒ [Options] をクリックして Options ダイアログを開き、[HTTPS] タブの [Actions] ボタンをクリックしてプルダウンを表示し、[Reset All Certificates] をクリックしてやります。

その先は表示される案内に従って進めていけば、「信頼されたルート証明機関」にインストールされた古い NOT_TRUST_FiddlerRoot 証明書が削除され、有効期限が延長された新しい証明書がインストールされます。

その際、[Decrypt HTTPS traffic] のチェックが外れることがあるようで、確認して外れていてらチェックを入れてください。

以上でエラーは解消できて、HTTPS 通信のトラフィックをキャプチャして表示できるようになるはずです。