.NET Core 3.0 使用Nswag生成Api文件和客戶端程式碼
摘要
在前後端分離、Restful API盛行的年代，完美的介面文件，成了交流的紐帶。在專案中引入Swagger （也稱為OpenAPI），是種不錯的選擇，它可以讓介面資料視覺化。下文將會演示
-
利用Nswag如何生成Api文件
-
利用NSwagStudio如何生成客戶端程式碼,並且進行測試
什麼是 Swagger/OpenAPI？
Swagger 是一個與語言無關的規範，用於描述 REST API。Swagger 專案已捐贈給 OpenAPI 計劃，現在它被稱為開放 API。這兩個名稱可互換使用，但 OpenAPI 是首選。它允許計算機和人員瞭解服務的功能，而無需直接訪問實現（原始碼、網路訪問、文件）。其中一個目標是儘量減少連線取消關聯的服務所需的工作量。另一個目標是減少準確記錄服務所需的時間。
Nswag VS Swashbuckle？
.NET Swagger 實現類庫有兩個比較流行：
-
Swashbuckle.AspNetCore 是一個開源專案，用於生成 ASP.NET Core Web API 的 Swagger 文件。
-
NSwag 是另一個用於生成 Swagger 文件並將 Swagger UI 或 ReDoc 整合到 ASP.NET Core Web API 中的開源專案。此外，NSwag 還提供了為 API 生成 C# 和 TypeScript 客戶端程式碼的方法。
為什麼我在.NET core3.0中選擇NSwag呢，NSwag比較活躍，一直在更新，功能也很強大，可以完美的代替Swashbuckle.AspNetCore具體可以參考：https://github.com/aspnet/AspNetCore.Docs/issues/4258
一、利用Nswag生成Api文件
步驟
-
建立Asp.NET Core Api專案，並且整合NSwag
-
配置專案
-
執行專案
建立Asp.NET Core Api專案，並且整合NSwag
我們將簡單的建立一個ASP.NET core API專案。將其命名為“WebAPIwithSwg”。基於.NETcore3.0
安裝nuget包NSwag.AspNetCore
接下來，在Startup.cs檔案中配置Nswag服務和中介軟體。
在ConfigureServices方法中新增服務
public void ConfigureServices(IServiceCollection services)
{
services.AddControllers();
services.AddSwaggerDocument(); //註冊Swagger 服務
}在Configure方法中新增Nswag中介軟體
public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
if (env.IsDevelopment())
{
app.UseDeveloperExceptionPage();
}
app.UseRouting();
app.UseAuthorization();
app.UseEndpoints(endpoints =>
{
endpoints.MapControllers();
});
app.UseOpenApi(); //新增swagger生成api文件（預設路由文件 /swagger/v1/swagger.json）
app.UseSwaggerUi3();//新增Swagger UI到請求管道中(預設路由: /swagger).
}
配置專案
執行專案
右鍵專案在瀏覽器中檢視，檢視swagger UI需要在url後面新增“/swagger”。本示例http://localhost:54117/swagger
二、利用NSwagStudio如何生成客戶端程式碼,並且進行測試
提供GUI介面是NSwag的一大特點，只需要下載安裝NSwagStudio，即可生成客戶端程式碼。
步驟
-
現在安裝NSwagStudio
-
NSwagStudio配置，生成客戶端程式碼
-
建立測試客戶端專案
下載安裝NSwagStudio
下載NSwag Studio http://rsuter.com/Projects/NSwagStudio/installer.php 安裝之後開啟 NSwag Studio 如圖
NSwagStudio配置，生成客戶端程式碼
選擇runtime，我選擇的是NETCore30,切換OpenAPI/Swagger Specification ,在Specification URL 輸入你的Swagger.json路徑，本示例：http://localhost:54117/swagger/v1/swagger.json輸入路徑之後，點選 create local copy 按鈕獲取json。
接下配置來生成客戶端程式碼。我們首先選擇“csharp client”複選框，然後勾選掉 “Inject Http Client via Constructor (life cycle is managed by caller)” ，最後設定下輸出路徑 點選生成檔案（Generate Files）。步驟如下
到此客戶端程式碼已經自動生成。
檢視生成的部分程式碼
public async System.Threading.Tasks.Task<System.Collections.Generic.ICollection<WeatherForecast>> GetAsync(System.Threading.CancellationToken cancellationToken)
{
var urlBuilder_ = new System.Text.StringBuilder();
urlBuilder_.Append(BaseUrl != null ? BaseUrl.TrimEnd('/') : "").Append("/WeatherForecast");
var client_ = new System.Net.Http.HttpClient();
try
{
using (var request_ = new System.Net.Http.HttpRequestMessage())
{
request_.Method = new System.Net.Http.HttpMethod("GET");
request_.Headers.Accept.Add(System.Net.Http.Headers.MediaTypeWithQualityHeaderValue.Parse("application/json"));
PrepareRequest(client_, request_, urlBuilder_);
var url_ = urlBuilder_.ToString();
request_.RequestUri = new System.Uri(url_, System.UriKind.RelativeOrAbsolute);
PrepareRequest(client_, request_, url_);
var response_ = await client_.SendAsync(request_, System.Net.Http.HttpCompletionOption.ResponseHeadersRead, cancellationToken).ConfigureAwait(false);
try
{
var headers_ = System.Linq.Enumerable.ToDictionary(response_.Headers, h_ => h_.Key, h_ => h_.Value);
if (response_.Content != null && response_.Content.Headers != null)
{
foreach (var item_ in response_.Content.Headers)
headers_[item_.Key] = item_.Value;
}
ProcessResponse(client_, response_);
var status_ = ((int)response_.StatusCode).ToString();
if (status_ == "200")
{
var objectResponse_ = await ReadObjectResponseAsync<System.Collections.Generic.ICollection<WeatherForecast>>(response_, headers_).ConfigureAwait(false);
return objectResponse_.Object;
}
else
if (status_ != "200" && status_ != "204")
{
var responseData_ = response_.Content == null ? null : await response_.Content.ReadAsStringAsync().ConfigureAwait(false);
throw new ApiException("The HTTP status code of the response was not expected (" + (int)response_.StatusCode + ").", (int)response_.StatusCode, responseData_, headers_, null);
}
return default(System.Collections.Generic.ICollection<WeatherForecast>);
}
finally
{
if (response_ != null)
response_.Dispose();
}
}
}
finally
{
if (client_ != null)
client_.Dispose();
}
}
建立測試客戶端專案
建立一個控制程式專案，命名“WebApiClient”。
把自動生成的類“WeatherForecastClient”新增到客戶端專案中，然後安裝Newtonsoft
最後在Main函式中新增測試程式碼，開始使用Api。
static async System.Threading.Tasks.Task Main(string[] args)
{
var weatherForecastClient = new WeatherForecastClient();
//gets all values from the API
var allValues = await weatherForecastClient.GetAsync();
Console.WriteLine("Hello World!");
}
執行客戶端應用程式，進行呼叫api
當然如果需要除錯api專案內部程式碼，可以設定斷點，進入一步一步的除錯
小結：NSwag 功能遠不止這些，本篇文章演示瞭如何生成api文件和自動生成的api客戶端程式碼方便我們除錯，也可以作為對應的sdk。
參考：微軟官方文件---https://docs.microsoft.com/zh-cn/aspnet/core/tutorials/getting-started-with-nswag?view=aspnetcore-2.2&tabs=visual-studio