.NET9中Swagger平替Scalar使用詳解

更新時間：2024年11月28日 09:28:11 作者：IT規(guī)劃師

本文詳細(xì)介紹了Swagger中常用功能在Scalar中的使用,包括版本說明、接口分類、接口及參數(shù)描述、枚舉類型、文件上傳和JWT認(rèn)證等,并提供相關(guān)代碼示例和效果展示,感興趣的朋友跟隨小編一起看看吧

01、版本說明

我們先來看看默認(rèn)添加后是什么樣子的。

public static void Main(string[] args)
{
    var builder = WebApplication.CreateBuilder(args);
    builder.Services.AddControllers();
    builder.Services.AddOpenApi();
    var app = builder.Build();
    app.MapScalarApiReference();
    app.MapOpenApi();
    app.UseAuthorization();
    app.MapControllers();
    app.Run();
}

效果如下：

我們可以直接修改builder.Services.AddOpenApi()這行代碼，修改這塊描述，代碼如下：

builder.Services.AddOpenApi(options =>
{
    options.AddDocumentTransformer((document, context, cancellationToken) =>
    {
        document.Info = new()
        {
            Title = "訂單微服務(wù)",
            Version = "v1",
            Description = "訂單相關(guān)接口"
        };
        return Task.CompletedTask;
    });
});

我們再來看看效果。

02、接口分類

通過上圖可以看到菜單左側(cè)排列著所有接口，現(xiàn)在我們可以通過Tags特性對接口進(jìn)行分類，如下圖我們把增刪改查4個方法分為冪等接口和非冪等接口兩類，如下圖：

然后我們看看效果，如下圖：

03、接口描述

之前使用Swagger我們都是通過生成的注釋XML來生成相關(guān)接口描述，現(xiàn)在則是通過編碼的方式設(shè)置元數(shù)據(jù)來生成相關(guān)描述。

可以通過EndpointSummary設(shè)置接口摘要，摘要不設(shè)置默認(rèn)為接口url，通過EndpointDescription設(shè)置接口描述，代碼如下：

//獲取
[HttpGet(Name = "")]
[Tags("冪等接口")]
[EndpointDescription("獲取訂單列表")]
public IEnumerable<Order> Get()
{
    return null;
}
//刪除
[HttpDelete(Name = "{id}")]
[Tags("冪等接口")]
[EndpointSummary("刪除訂單")]
[EndpointDescription("根據(jù)訂單id，刪除相應(yīng)訂單")]
public bool Delete(string id)
{
    return true;
}

運行效果如下：

04、參數(shù)描述

同樣可以通過Description特性來設(shè)置參數(shù)的描述，并且此特性可以直接作用于接口中參數(shù)之前，同時也支持作用于屬性上，可以看看下面示例代碼。

public class Order
{
    [property: Description("創(chuàng)建日期")]
    public DateOnly Date { get; set; }
    [property: Required]
    [property: DefaultValue(120)]
    [property: Description("訂單價格")]
    public int Price { get; set; }
    [property: Description("訂單折扣價格")]
    public int PriceF => (int)(Price * 0.5556);
    [property: Description("商品名稱")]
    public string? Name { get; set; }
}
[HttpPut(Name = "{id}")]
[Tags("非冪等接口")]
public bool Put([Description("訂單Id")] string id, Order order)
{
    return true;
}

效果如下圖：

從上圖可以發(fā)現(xiàn)除了描述還有默認(rèn)值、必填項、可空等字樣，這些是通過其他元數(shù)據(jù)設(shè)置的，對于屬性還有以下元數(shù)據(jù)可以進(jìn)行設(shè)置。

05、枚舉類型

對于枚舉類型，我們正常關(guān)注兩個東西，其一為枚舉項以int類型展示還是以字符串展示，其二為枚舉項顯示描述信息。

關(guān)于第一點比較簡單只要對枚舉類型使用JsonStringEnumConverter即可，代碼如下：

[JsonConverter(typeof(JsonStringEnumConverter<OrderStatus>))]
public enum OrderStatus
{
    [Description("等待處理")]
    Pending = 1,
    [Description("處理中")]
    Processing = 2,
    [Description("已發(fā)貨")]
    Shipped = 3,
    [Description("已送達(dá)")]
    Delivered = 4,
}

效果如下：

通過上圖也可以引發(fā)關(guān)于第二點的需求，如何對每個枚舉項添加描述信息。

要達(dá)到這個目標(biāo)需要做兩件事，其一給每個枚舉項通過Description添加元數(shù)據(jù)定義，其二我們要修改文檔的數(shù)據(jù)結(jié)構(gòu)Schema。

修改builder.Services.AddOpenApi()，通過AddSchemaTransformer方法修改文檔數(shù)據(jù)結(jié)構(gòu)，代碼如下：

options.AddSchemaTransformer((schema, context, cancellationToken) =>
{
    //找出枚舉類型
    if (context.JsonTypeInfo.Type.BaseType == typeof(Enum))
    {
        var list = new List<IOpenApiAny>();
        //獲取枚舉項
        foreach (var enumValue in schema.Enum.OfType<OpenApiString>())
        {
            //把枚舉項轉(zhuǎn)為枚舉類型
            if (Enum.TryParse(context.JsonTypeInfo.Type, enumValue.Value, out var result))
            {
                //通過枚舉擴(kuò)展方法獲取枚舉描述
                var description = ((Enum)result).ToDescription();
                //重新組織枚舉值展示結(jié)構(gòu)
                list.Add(new OpenApiString($"{enumValue.Value} - {description}"));
            }
            else
            {
                list.Add(enumValue);
            }
        }
        schema.Enum = list;
    }
    return Task.CompletedTask;
});

我們再來看看結(jié)果。

但是這也帶來了一個問題，就是參數(shù)的默認(rèn)值也是添加描述的格式，顯然這樣的數(shù)據(jù)格式作為參數(shù)肯定是錯誤的，因此我們需要自己注意，如下圖。目前我也沒有發(fā)現(xiàn)更好的方式即可以把每項枚舉描述加上，又不影響參數(shù)默認(rèn)值，有解決方案的希望可以不吝賜教。

06、文件上傳

下面我們來看看文件上傳怎么用，直接上代碼：

[HttpPost("upload/image")]
[EndpointDescription("圖片上傳接口")]
[DisableRequestSizeLimit]
public bool UploadImgageAsync(IFormFile file)
{
    return true;
}

然后我們測試一下效果。

首先我們可以看到請求示例中相關(guān)信息，這個相當(dāng)于告訴我們后面要怎么選擇文件上傳，我們繼續(xù)點擊Test Request。

首先請求體需要選擇multipart/form-data，上圖請求示例中已經(jīng)給出提示。

然后設(shè)置key為file，上圖請求示例中已經(jīng)給出提示，然后點擊File上傳圖片，最后點擊Send即可。

07、JWT認(rèn)證

最后我們來看看如何使用JWT認(rèn)證，

首先我們需要注入AddAuthentication及AddJwtBearer，具體代碼如下：

public class JwtSettingOption
{
    //這個字符數(shù)量有要求，不能隨便寫，否則會報錯
    public static string Secret { get; set; } = "123456789qwertyuiopasdfghjklzxcb";
    public static string Issuer { get; set; } = "asdfghjkkl";
    public static string Audience { get; set; } = "zxcvbnm";
    public static int Expires { get; set; } = 120;
    public static string RefreshAudience { get; set; } = "zxcvbnm.2024.refresh";
    public static int RefreshExpires { get; set; } = 10080;
}
builder.Services.AddAuthentication(options =>
{
    options.DefaultAuthenticateScheme = JwtBearerDefaults.AuthenticationScheme;
    options.DefaultChallengeScheme = JwtBearerDefaults.AuthenticationScheme;
}).AddJwtBearer(options =>
{
    //取出私鑰
    var secretByte = Encoding.UTF8.GetBytes(JwtSettingOption.Secret);
    options.TokenValidationParameters = new TokenValidationParameters()
    {
        //驗證發(fā)布者
        ValidateIssuer = true,
        ValidIssuer = JwtSettingOption.Issuer,
        //驗證接收者
        ValidateAudience = true,
        ValidAudiences = new List<string> { JwtSettingOption.Audience, JwtSettingOption.Audience },
        //驗證是否過期
        ValidateLifetime = true,
        //驗證私鑰
        IssuerSigningKey = new SymmetricSecurityKey(secretByte),
        ClockSkew = TimeSpan.FromHours(1), //過期時間容錯值，解決服務(wù)器端時間不同步問題（秒）
        RequireExpirationTime = true,
    };
});

然后我們需要繼續(xù)修改builder.Services.AddOpenApi()這行代碼，在里面加上如下代碼：

其中BearerSecuritySchemeTransformer實現(xiàn)如下：

public sealed class BearerSecuritySchemeTransformer(IAuthenticationSchemeProvider authenticationSchemeProvider) : IOpenApiDocumentTransformer
{
    public async Task TransformAsync(OpenApiDocument document, OpenApiDocumentTransformerContext context, CancellationToken cancellationToken)
    {
        var authenticationSchemes = await authenticationSchemeProvider.GetAllSchemesAsync();
        if (authenticationSchemes.Any(authScheme => authScheme.Name == JwtBearerDefaults.AuthenticationScheme))
        {
            var requirements = new Dictionary<string, OpenApiSecurityScheme>
            {
                [JwtBearerDefaults.AuthenticationScheme] = new OpenApiSecurityScheme
                {
                    Type = SecuritySchemeType.Http,
                    Scheme = JwtBearerDefaults.AuthenticationScheme.ToLower(),
                    In = ParameterLocation.Header,
                    BearerFormat = "Json Web Token"
                }
            };
            document.Components ??= new OpenApiComponents();
            document.Components.SecuritySchemes = requirements;
            foreach (var operation in document.Paths.Values.SelectMany(path => path.Operations))
            {
                operation.Value.Security.Add(new OpenApiSecurityRequirement
                {
                    [new OpenApiSecurityScheme
                    {
                        Reference = new OpenApiReference
                        {
                            Id = JwtBearerDefaults.AuthenticationScheme,
                            Type = ReferenceType.SecurityScheme
                        }
                    }] = Array.Empty<string>()
                });
            }
        }
    }
}

下面就可以通過[Authorize]開啟接口認(rèn)證，并實現(xiàn)一個登錄接口獲取token用來測試。

[HttpPost("login")]
[EndpointDescription("登錄成功后生成token")]
[AllowAnonymous]
public string  Login()
{
    //登錄成功返回一個token
    // 1.定義需要使用到的Claims
    var claims = new[] { new Claim("UserId", "test") };
    // 2.從 appsettings.json 中讀取SecretKey
    var secretKey = new SymmetricSecurityKey(Encoding.UTF8.GetBytes(JwtSettingOption.Secret));
    // 3.選擇加密算法
    var algorithm = SecurityAlgorithms.HmacSha256;
    // 4.生成Credentials
    var signingCredentials = new SigningCredentials(secretKey, algorithm);
    var now = DateTime.Now;
    var expires = now.AddMinutes(JwtSettingOption.Expires);
    // 5.根據(jù)以上，生成token
    var jwtSecurityToken = new JwtSecurityToken(
        JwtSettingOption.Issuer,         //Issuer
        JwtSettingOption.Audience,       //Audience
        claims,                          //Claims,
        now,                             //notBefore
        expires,                         //expires
        signingCredentials               //Credentials
    );
    // 6.將token變?yōu)閟tring
    var token = new JwtSecurityTokenHandler().WriteToken(jwtSecurityToken);
    return token;
}

下面我們先用登錄接口獲取一個token。