基於.NET Core 3.1的WebApi集成swagger

===============================================

 2020/1/8_第1次修改                       ccb_warlock

 

===============================================

swagger作為Asp .Net的接口文檔已經應用於當前系統一段時間了，比起開個postman填參數請求來說這個后台開發可以直接用swagger來快速測試接口的業務，前端開發通過查看swagger可以快速了解后台API的輸入輸出（畢竟開發進度緊張的情況下不可能來得及及時維護文檔，但是開發環境的swagger只要代碼更新就會一起更新）

最近為了試驗EF Core 2.2的datetime類型存在的一個缺陷，公司也沒有1個.net core 3.0以上的項目，沒辦法只有先改造.net core 2.2的項目到.net core 3.1以后，再進行下一步測試。

在做框架升級的時候，不得不實現swagger升級的問題。而swagger的升級問題花了點時間來處理，所以記錄下過程方便以后查看。

 

---

現在的穩定版還不支持.net core 3.0+，所以Nuget里需要升級下面2個項目到5.0.0以上的預覽版才能實現swagger的升級。

Swashbuckle.AspNetCore（勾選上預發行，當前要v5.0.0-rc5以上版本）

Swashbuckle.AspNetCore.Filters（勾選上預發行，當前要v5.0.0-rc9以上版本）

 

由於當前系統的框架用了很多注入，為了簡化描述我還是拆出來記錄代碼片段。

1）在Startup.cs中，通過ConfigureServices初始化swagger

public IServiceProvider ConfigureServices(IServiceCollection services)
{
    var title = "myApi";
    var version = "v1";
    
    services.AddControllers();
    services.AddSwaggerGen(c =>
    {
        // swagger文檔配置
        c.SwaggerDoc(version, new OpenApiInfo
        {
            Version = version,
            Title = title,
            //Description = $"{title} HTTP API " + v,
            //Contact = new OpenApiContact { Name = "Contact", Email = "[e-mail]", Url = new Uri("https://www.cnblogs.com/straycats/") },
            //License = new OpenApiLicense { Name = "License", Url = new Uri("https://www.cnblogs.com/straycats/") }
         });
         
         // 接口排序
         c.OrderActionsBy(o => o.RelativePath);

         // 配置xml文檔
         var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
         c.IncludeXmlComments(xmlPath);

         c.OperationFilter<AddResponseHeadersFilter>();
         c.OperationFilter<AppendAuthorizeToSummaryOperationFilter>();
         // 安全校驗
         c.OperationFilter<SecurityRequirementsOperationFilter>();

         // 開啟oauth2安全描述
        c.AddSecurityDefinition("oauth2", new OpenApiSecurityScheme
        {
            Description = "JWT授權(數據將在請求頭中進行傳輸) 直接在下框中輸入Bearer {token}（注意兩者之間是一個空格）\"",
            Name = "Authorization",
            In = ParameterLocation.Header,
            Type = SecuritySchemeType.ApiKey
         });
    });
}

 

2）在Startup.cs中，通過Configure在管道中添加swagger

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    var title = "myApi";
    
    if (env.IsDevelopment())
    {
        app.UseDeveloperExceptionPage();
    }
    else
    {
        app.UseHsts();
    }
    
    //啟用中間件服務生成Swagger作為JSON終結點
    app.UseSwagger();

    //啟用中間件服務對swagger-ui，指定Swagger JSON終結點
    app.UseSwaggerUI(c =>
    {
        c.SwaggerEndpoint("/swagger/v1/swagger.json", title);//注意這里的v1是根據上面的version來填的
    });

    app.UseRouting();
    app.UseAuthorization();
    app.UseEndpoints(endpoints =>
    {
        endpoints.MapControllers();
    });
}

 

運行后的接口清單

 

運行后的請求結果

 

 

---

參考資料：

1.https://docs.microsoft.com/zh-cn/aspnet/core/tutorials/getting-started-with-swashbuckle?view=aspnetcore-3.0&tabs=visual-studio

2.https://www.cnblogs.com/laozhang-is-phi/p/11520048.html

3.https://q.cnblogs.com/q/120085/

4.https://blog.csdn.net/qq_25086397/article/details/103682863