Swaggerの設定で見落としがちな属性について

永続的な認証の有効化


app.UseSwaggerUI(c =>
{
    // Swagger JSONファイルのエンドポイントを指定し、APIドキュメントを読み込んで表示します。
    c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");

    // 永続的な認証を有効にします
    c.EnablePersistAuthorization();
});

この設定により、トークンを入力した後、毎回再入力する必要がなくなります。これは、SwaggerがJavaScriptコードを使用して自動ログインを行うためです。

コントローラーのXMLコメント


public static class SwaggerSetup
{
    public static IServiceCollection AddSwaggerSetup(this IServiceCollection services)
    {
        Action<SwaggerGenOptions> defaultSetupAction = options =>
        {
            var basePath = AppContext.BaseDirectory;

            options.SwaggerDoc("v1",
                new OpenApiInfo
                {
                    Title = "オンラインAPIドキュメント",
                    Version = "v1"
                });

            // ベースディレクトリ内のすべてのXMLファイルの完全パスを取得
            var directoryInfo = new DirectoryInfo(basePath);
            List<string> xmls = directoryInfo
                .GetFiles()
                .Where(f => f.Name.ToLower().EndsWith(".xml"))
                .Select(f => f.FullName)
                .ToList();

            // XMLコメントを追加
            foreach (var xml in xmls)
            {
                options.IncludeXmlComments(xml, true);
            }

            // JWT認証の設定
            options.AddSecurityDefinition("Bearer", new OpenApiSecurityScheme
            {
                Scheme = "Bearer",
                BearerFormat = "JWT",
                Description = "以下のボックスにトークンを入力してください",
                Name = "Authorization",
                In = ParameterLocation.Header,
                Type = SecuritySchemeType.Http
            });
        };

        // Swaggerの登録とデフォルト設定の追加
        services.AddSwaggerGen(defaultSetupAction);

        return services;
    }
}

`options.IncludeXmlComments(xml, true);` の第二引数は、コントローラーにコメントを追加するかどうかを制御します。

Try It Outリクエストの持続時間の表示


app.UseSwaggerUI(c =>
{
    // Swagger JSONファイルのエンドポイントを指定し、APIドキュメントを読み込んで表示します。
    c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");

    // Try It Outリクエストの持続時間をミリ秒単位で表示します
    c.DisplayRequestDuration();
});

Swagger UIのルート設定


app.UseSwaggerUI(c =>
{
    // Swagger JSONファイルのエンドポイントを指定し、APIドキュメントを読み込んで表示します。
    c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");

    // Swaggerドキュメントの起動ディレクトリを指定します。デフォルトは"swagger"です。
    // 空文字列を設定すると、Swagger UIはルートパスから直接アクセスできます。
    // c.RoutePrefix = string.Empty;
});

ドキュメントの展開方法


app.UseSwaggerUI(c =>
{
    // Swagger JSONファイルのエンドポイントを指定し、APIドキュメントを読み込んで表示します。
    c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");

    // デフォルトのインターフェースドキュメントの展開方法を設定します。オプションはNone、List、Fullです。
    // None: ドキュメントを展開しない
    // List: インターフェースリストのみ展開
    // Full: すべてのインターフェース詳細を展開
    c.DocExpansion(DocExpansion.None); // 完全モードに設定
    c.DisplayRequestDuration();
    c.EnablePersistAuthorization();
});

タグ: Swagger ASP.NET Core OpenAPI XML Comments JWT Authentication

5月18日 19:30 投稿