.net core 3.0_webapi項目使用Swagger提供接口幫助頁面

　　前言：我們開發了很多的接口后，為了方便調用人員使用，需要給出接口地址，參數和解釋說明，可能還需要示例。  那么swagger這個開源項目，已經給我們提供好了一整套的解決方案：

　　本博客參考文檔：

　　Swashbuckle 和 ASP.NET Core 入門  

　　

　　什么是 Swagger/OpenAPI？

Swagger 是一個與語言無關的規范，用於描述 REST API。 Swagger 項目已捐贈給 OpenAPI 計划，現在它被稱為開放 API。 這兩個名稱可互換使用，但 OpenAPI 是首選。 它允許計算機和人員了解服務的功能，而無需直接訪問實現（源代碼、網絡訪問、文檔）。 其中一個目標是盡量減少連接取消關聯的服務所需的工作量。 另一個目標是減少准確記錄服務所需的時間。（說明參考微軟官方文檔：https://docs.microsoft.com/zh-cn/aspnet/core/tutorials/web-api-help-pages-using-swagger?view=aspnetcore-3.0）

 

　　快速添加webapi項目對swagger的支持：

　　1-添加程序包引用：Swashbuckle.AspNetCore -Version 5.0.0-rc4   (該版本目前屬於預覽版，需要勾選預覽版才可以看到)

　  2-添加並配置 Swagger 中間件：

　　

using Microsoft.OpenApi.Models; public void ConfigureServices(IServiceCollection services)
{
    // Register the Swagger generator, defining 1 or more Swagger documents
            services.AddSwaggerGen(c => { c.SwaggerDoc("v1", new OpenApiInfo { Title = "My API", Version = "v1" }); // include document file
                c.IncludeXmlComments(Path.Combine(AppContext.BaseDirectory, $"{typeof(Startup).Assembly.GetName().Name}.xml"), true); });

    services.AddControllers();
}

　　這里，需要添加對項目xml文件的引用，默認啟用根目錄下的項目文件名的xml文件，項目xml文件生成配置如下：

　　為了兼容發布版本，咱們設置了輸出路徑為空，xml名稱改為：項目名.xml  

 

 

 

　　3-在 Startup.Configure 方法中，啟用中間件為生成的 JSON 文檔和 Swagger UI 提供服務：

　　

public void Configure(IApplicationBuilder app)
{
    // Enable middleware to serve generated Swagger as a JSON endpoint.
 app.UseSwagger(); // Enable middleware to serve swagger-ui (HTML, JS, CSS, etc.), // specifying the Swagger JSON endpoint.
    app.UseSwaggerUI(c => { c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1"); });

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

 

　　4-結束，查看效果：

　　

　　啟動應用，並導航到： http://localhost:<port>/swagger/v1/swagger.json。 生成的描述終結點的文檔顯示在 Swagger 規范 (swagger.json) 中。

　　可在 http://localhost:<port>/swagger  找到 Swagger UI。 通過 Swagger UI 瀏覽 API

 

 

 

 

　　5-走過的坑1：官網文檔前半部分並沒有讓添加xml文件的代碼。后面有涉及，不過還是感覺有點亂，本博客已加上！

　　走過的坑2：常見異常：Ambiguous HTTP method for action - PaymentAccountAPI.Controllers.PayAccountController.GetTransactions (PaymentAccountAPI). Actions require an explicit HttpMethod binding for Swagger/OpenAPI 3.0

　　該異常是因為控制器方法，缺少方法類型的標記，[HttpGet]、[HttpPost],如下圖：

　　參考解決方案文檔：Ambiguous HTTP method Actions require an explicit HttpMethod binding for Swagger 2.0

　　

 

 

 　　走過的坑3：缺少xml項目文件異常_500錯誤：    項目部署到IIS后，不會自動把xml文件帶過去，需要我們收到復制過去，在運行查看效果。

　　

 

 

　　 把項目xml文件放入后，再試（需要重啟IIS項目），效果正常：