1.什么是Swagger/OpenAPI？

Swagger是一個與語言無關(guān)的規(guī)范，用于描述REST API。因為Swagger項目已捐贈給OpenAPI計劃，所以也叫OpenAPI。它允許計算機和人員了解服務(wù)的功能，可以直接在線訪問測試API方法。而Swagger UI提供了基于Web的UI，它使用生成的Swagger規(guī)范提供有關(guān)服務(wù)API的信息。Swashbuckle和NSwag均包含Swagger UI的嵌入式版本，因此可使用中間件注冊調(diào)用將該嵌入式版本托管在ASP.NET Core應(yīng)用程序當(dāng)中。Swagger的核心是Swagger規(guī)范，默認情況下是名為swagger.json的文檔。它由Swagger工具鏈（或其第三方實現(xiàn)）根據(jù)你的服務(wù)生成。它描述了API的功能以及使用HTTP對其進行訪問的方式。它驅(qū)動Swagger UI，并由工具鏈用來啟用發(fā)現(xiàn)和客戶端代碼生成。

2.NET Swagger實現(xiàn)

NET Swagger實現(xiàn)分為兩大分類：

• Swashbuckle.AspNetCore是一個開源項目，用于生成ASP.NET Core Web API的Swagger文檔。
• NSwag是另一個用于生成Swagger文檔并將Swagger UI或ReDoc集成到ASP.NET Core Web API中的開源項目。此外，NSwag 還提供了為API生成C#和TypeScript客戶端代碼的方法。

但是由于工作比較忙，我就不打算兩個類型都講了，我只選擇Swashbuckle.AspNetCore來講解和演示。

3.Swashbuckle主要組成部分

Swashbuckle有三個主要組成部分：

• Swashbuckle.AspNetCore.Swagger：將SwaggerDocument對象公開為JSON終結(jié)點的Swagger對象模型和中間件。
• Swashbuckle.AspNetCore.SwaggerGen：從路由、控制器和模型直接生成SwaggerDocument對象的Swagger生成器。它通常與Swagger終結(jié)點中間件結(jié)合，以自動公開Swagger JSON。
• Swashbuckle.AspNetCore.SwaggerUI：Swagger UI工具的嵌入式版本。它解釋Swagger JSON以構(gòu)建描述Web API功能的可自定義的豐富體驗，它包括針對公共方法的內(nèi)置測試工具。

安裝Swashbuckle組件方法有兩種：

--PowerShell
Install-Package Swashbuckle.AspNetCore -Version 5.0.0

or

--.NET Core CLI
dotnet add TodoApi.csproj package Swashbuckle.AspNetCore -v 5.0.0

4.什么是REST?

我百度一下，度娘解釋是：REST是（Representational State Transfer）“表現(xiàn)層狀態(tài)轉(zhuǎn)移”的縮寫，它是由羅伊·菲爾丁（Roy Fielding）提出的，是用來描述創(chuàng)建HTTP API的標準方法，他發(fā)現(xiàn)這四種常用的行為“查看（view），創(chuàng)建（create），編輯（edit）和刪除（delete）”都可以直接映射到HTTP中已實現(xiàn)的GET、POST、PUT和DELETE方法。

5.配置Swagger中間件

將Swagger生成器添加到Startup.ConfigureServices方法中的服務(wù)集合中：

//注冊Swagger生成器，定義一個或多個Swagger文檔.
services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1", new OpenApiInfo { Title = "My API", Version = "v1", Description = "測試描述" });
});

OpenApiInfo對象是用來標識Swagger文檔信息（諸如作者、許可證和說明的信息），您還可以自定義您的主題的信息顯示在UI上，詳情配置，我就不多說，大家可以看官網(wǎng)描述，如上述OpenApilnfo信息配置示例圖：

而在啟動應(yīng)用程序后并導(dǎo)航到http://localhost:<port>/swagger/v1/swagger.json。生成的描述終結(jié)點的文檔顯示在Swagger規(guī)范（swagger.json）中：

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

//使中間件能夠?qū)⑸傻腟wagger用作JSON端點.
app.UseSwagger();
//允許中間件為swagger ui（HTML、JS、CSS等）提供服務(wù)，指定swagger JSON端點.
app.UseSwaggerUI(c =>
{
    c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
});

根據(jù)上述配置就能夠啟用swagger測試API服務(wù)接口了，如下圖所示：

6.XML注釋

swagger還可以把服務(wù)API中對應(yīng)方法名稱，實體屬性注釋給在UI上顯示出來，讓您更加直觀了解每個方法使用信息，并對沒有注釋每個方法進行警告提示，具體啟用XML注釋操作在“解決方案資源管理器”中右鍵單擊該項目，然后選擇“編輯<project_name>.csproj”，手動將突出顯示的行添加到.csproj 文件：

<PropertyGroup>
  <GenerateDocumentationFile>true</GenerateDocumentationFile>
</PropertyGroup>

在啟用了XML注釋后，swagger只會針對沒有添加注釋每個方法進行警告提示，而添加了注釋的方法則不會進行警告提示：

而每個添加了注釋的方法會通過在Startup.ConfigureServices/services.AddSwaggerGen中設(shè)置Swagger JSON和UI的注釋路徑后：

//設(shè)置Swagger JSON和UI的注釋路徑.
var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
c.IncludeXmlComments(xmlPath);

會在項目根目錄生成的一個對應(yīng)項目文件名的XML文件，而文件里面就包含所有已注釋的方法，用于UI上顯示：

在啟動應(yīng)用程序后，我們會看到每個有注釋方法在左側(cè)會有一行文字描述，效果如下圖所示：

如果某個方法或者類下面所有方法不想警告提示，可以通過加入#pragma warning disable聲明屏蔽警告提示：

加入聲明之后，大家會看到警告提示消失了。

7.數(shù)據(jù)注釋

可以使用System.ComponentModel.DataAnnotations命名空間中的屬性來標記模型實體，以幫助驅(qū)動Swagger UI 組件。將[Required]屬性添加到TodoItem類的Name屬性：

namespace TodoApi.Models
{
    public class TodoItem
    {
        public long Id { get; set; }
        [Required]
        public string Name { get; set; }
        [DefaultValue(false)]
        public bool IsComplete { get; set; }
    }
}

此屬性的狀態(tài)會更改掉基礎(chǔ)JSON架構(gòu)：

而將[Produces("application/json")]屬性添加到API控制器去，這樣做的目的是聲明控制器的操作支持application/json的響應(yīng)內(nèi)容類型：

[Produces("application/json")]
[Route("api/[controller]")]
[ApiController]
public class ValuesController : ControllerBase
{
    /// <summary>
    /// 獲取值
    /// </summary>
    /// <returns></returns>
    // GET api/values
    [HttpGet]
    public async Task<ActionResult<IEnumerable<string>>> Get()
    {
        var result = await new GitHubApi().GetUser();
        return new string[] { result.id.Value.ToString(), result.login };
    }
}

“響應(yīng)內(nèi)容類型”下拉列表選此內(nèi)容類型作為控制器的默認GET操作：

Swagger/OpenAPI出現(xiàn)，大大減少開發(fā)者調(diào)試時間，增加開發(fā)者開發(fā)效率，讓開發(fā)者更加方便調(diào)試跟直觀了解對應(yīng)服務(wù)方法。

以上就是本文的全部內(nèi)容，希望對大家的學(xué)習(xí)有所幫助，也希望大家多多支持腳本之家。

最新評論