Swagger 接口文檔管理

Swagger是我們的好朋友，讓後端不用再寫文檔(當然文檔該寫的還得寫)

但是更方便我們對自己接口的測試，推薦使用Swagger 進行接口文檔管理

這裏簡單介紹比較常用的的點，
一定要提官方文檔
https://docs.microsoft.com/zh-cn/aspnet/core/tutorials/getting-started-with-swashbuckle?view=aspnetcore-6.0&tabs=visual-studio 文檔比我寫的講的詳細

1.Swagger 註釋

我們要把打開Xml文件生成
首先打開你項目的.csproj文件
打開方式 右鍵項目 -> 編輯項目文件

我們希望在每個方法後面添加介紹，以便於我們測試和前端的閲讀

我們要打開XML文檔文件生成

首先打開你項目的.csproj文件

打開方式 右鍵項目 -> 編輯項目文件

<PropertyGroup>
    //加上底下這行代碼
    <GenerateDocumentationFile>True</GenerateDocumentationFile>
</PropertyGroup>

或者

右鍵項目 -> 屬性 -> 生成 -> 輸出 -> 文檔文件 -> 勾選上生成包含API文檔的文件

然後Progarm.cs 添加如下代碼

builder.Services.AddSwaggerGen(options => {
    //註釋
    var xmlFilename = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
    //第二個參數為是否顯示控制器註釋,我們選擇true
    options.IncludeXmlComments(Path.Combine(AppContext.BaseDirectory, xmlFilename),true);
});

2.簡單版本控制

首先我們創建個枚舉類

/// <summary>
/// Api版本枚舉類
/// </summary>
public enum ApiVersions
{
   /// <summary>
   /// 版本V1
   /// </summary>
   V1=1,
   /// <summary>
   /// 版本V2
   /// </summary>
   V2=2
}

然後添加如下代碼

builder.Services.AddSwaggerGen(options => {
    /*
    //只有參數裏的V1是要和下面配置路徑保持一致,
    //剩下的亂寫也不報錯 但是不推薦
     options.SwaggerDoc("V1", new OpenApiInfo 
        {
            Title = $"項目名",
            Version = "V1",
            Description = $"項目名:V1版本"
        });
    */
    //生成多個文檔顯示
    typeof(ApiVersions).GetEnumNames().ToList().ForEach(version =>
    {
        //添加文檔介紹
        options.SwaggerDoc(version, new OpenApiInfo
        {
            Title = $"項目名",
            Version = version,
            Description = $"項目名:{version}版本"
        });
    });
});

和

if (app.Environment.IsDevelopment())
{
    app.UseSwagger();
    app.UseSwaggerUI(options => {
        
        /*
         options.SwaggerEndpoint($"/swagger/V1/swagger.json",$"版本選擇:V1");
        */
        //如果只有一個版本也要和上方保持一致
        typeof(ApiVersions).GetEnumNames().ToList().ForEach(version =>
        {
            //切換版本操作
            //參數一是使用的哪個json文件,參數二就是個名字
            options.SwaggerEndpoint($"/swagger/{version}/swagger.json",$"版本選擇:{version}");
        });
    });
}

最後在我們的控制器上方加上特性

[ApiExplorerSettings(GroupName ="V1")]
[HttpGet]
public IEnumerable<WeatherForecast> Get(Wea weather)
{
    return Enumerable.Range(1, 5).Select(index => new WeatherForecast
    {
        Date = DateTime.Now.AddDays(index),
        TemperatureC = Random.Shared.Next(-20, 55),
        Summary = Summaries[Random.Shared.Next(Summaries.Length)]
    })
    .ToArray();
}

3.添加Jwt認證功能

添加如下代碼

builder.Services.AddSwaggerGen(options => 
{
    options.AddSecurityDefinition("Bearer", new OpenApiSecurityScheme()
    {
        Description = "在下框中輸入請求頭中需要添加Jwt授權Token：Bearer Token",
        Name = "Authorization",
        In = ParameterLocation.Header,
        Type = SecuritySchemeType.ApiKey,
        BearerFormat = "JWT",
        Scheme = "Bearer"
    });
    options.AddSecurityRequirement(new OpenApiSecurityRequirement
    {
        {
            new OpenApiSecurityScheme
            {
                Reference = new OpenApiReference {
                    Type = ReferenceType.SecurityScheme,
                    Id = "Bearer"
                }
            },
            new string[] { }
        }
    });
});

轉載自https://bxshare.top/index.php/archives/12/