一、什麼是Swagger

隨著技術的不斷方法，現在的網站開發基本都是使用前後端分離的模式，這樣使前端開發者和後端開發者只需要專注自己擅長的即可。但這種方式會存在一種問題：前後端通過API介面的方式進行呼叫，介面文件的好壞可以決定開發的進度。以前如果使用Word的形式提供介面文件，或多或少的都會存在各種問題。前端抱怨說後端給的介面文件與實際情況不一致。而後端開發人員又覺得編寫以及維護介面文件很費精力，文件經常不能及時更新，導致前端看到的還是舊的介面文件。這時候就需要使用Swagger了。

那麼什麼是Swagger呢？Swagger是最流行的API開發工具，它遵循了OpenAPI規範，可以根據API介面自動生成線上文件，這樣就可以解決文件更新不及時的問題。它可以貫穿於整個API生態，比如API的設計、編寫API文件等。而且Swagger還是一種通用的、與具體程式語言無關的API描述規範。

有關更多Swagger的介紹，可以參考Swagger官網，官網地址：https://swagger.io/

二、ASP.NET Core中使用Swagger

這裡使用最新的ASP.NET Core 3.1建立WebAPI介面。關於如何建立WebAPI這裡不在描述。建立後的WebAPI專案結構如下：

1、新增Swagger

直接在NuGet裡面搜尋Swashbuckle.AspNetCore包進行安裝：

2、新增服務

在Startup類的ConfigureServices方法裡面注入服務：

public void ConfigureServices(IServiceCollection services)
{
    
 
// 新增Swagger
    services.AddSwaggerGen(c =>
    {
        c.SwaggerDoc("v1", new OpenApiInfo { Title = "API Demo", Version = "v1" });
    });
    services.AddControllers();
}

3、新增中介軟體

在Startup類的Configure方法裡面新增Swagger有關的中介軟體：

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    
 
if (env.IsDevelopment())
    {
        app.UseDeveloperExceptionPage();
    }

    // 新增Swagger有關中介軟體
    app.UseSwagger();
    app.UseSwaggerUI(c =>
    {
        c.SwaggerEndpoint("/swagger/v1/swagger.json", "API Demo v1");
    });

    app.UseRouting();

    app.UseAuthorization();

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

4、新增控制器

新建一個控制器，裡面包括基礎的增刪改查方法：

using Microsoft.AspNetCore.Mvc;

namespace SwaggerDemo.Controllers
{
    [Route("api/student")]
    [ApiController]
    public class StudentController : ControllerBase
    {
        [HttpGet]
        public string Get()
        {
            return "Tom";
        }

        [HttpPost]
        public void Post()
        {
            
        }

        [HttpPut]
        public void Put()
        {

        }

        [HttpDelete]
        public void Delete()
        {

        }
    }
}

執行程式，修改一下url地址：

http://localhost:5000/swagger/index.html

如下圖所示：

這樣就可以看到介面了。但這樣還不是我們最終想要的結果，我們想知道每個方法的註釋和方法引數的註釋，這就需要對介面做XML註釋了。首先安裝Microsoft.Extensions.PlatformAbstractions包：

然後修改ConfigureServices方法，增加下面的方法：

public void ConfigureServices(IServiceCollection services)
{
    #region 新增Swagger
    services.AddSwaggerGen(options =>
    {
        options.SwaggerDoc("v1",new  OpenApiInfo { Title = "My API", Version = "v1" });
        // 獲取xml檔名
        var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
        // 獲取xml檔案路徑
        var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
        // 新增控制器層註釋，true表示顯示控制器註釋
        options.IncludeXmlComments(xmlPath, true);
    });
    #endregion
    services.AddControllers();
}

然後給新建的介面添加註釋：

using Microsoft.AspNetCore.Mvc;

namespace SwaggerDemo.Controllers
{

    /// <summary>
    /// 學生控制器
    /// </summary>
    [Route("api/student")]
    [ApiController]
    public class StudentController : ControllerBase
    {
        /// <summary>
        /// 獲取所有學生
        /// </summary>
        /// <returns></returns>
        [HttpGet]
        public string Get()
        {
            return "Tom";
        }

        /// <summary>
        /// 新增學生
        /// </summary>
        [HttpPost]
        public void Post()
        {
            
        }

        /// <summary>
        /// 修改學生資訊
        /// </summary>
        [HttpPut]
        public void Put()
        {

        }

        /// <summary>
        /// 刪除學生資訊
        /// </summary>
        [HttpDelete]
        public void Delete()
        {

        }
    }
}

專案右鍵，選擇屬性，勾選“XML文件檔案”，如下圖所示：

在執行程式：

可以看到，剛才在控制器上面新增的註釋資訊都顯示出來了。這樣前端就可以直接檢視介面文件了。

三、總結

上面簡單介紹了什麼是Swagger，以及如何利用Swagger進行除錯，這樣只需要啟動程式即可，不需要在額外的使用Postman進行測試。使用Swagger可以保持介面文件能夠及時更新。

轉自;https://www.cnblogs.com/dotnet261010/p/12425572.html