摘要

在前后端分離、Restful API盛行的年代，完美的接口文檔，成了交流的紐帶。在項目中引入Swagger （也稱為OpenAPI），是種不錯的選擇，它可以讓接口數(shù)據(jù)可視化。下文將會演示

• 利用Nswag如何生成Api文檔

• 利用NSwagStudio如何生成客戶端代碼,并且進(jìn)行測試

什么是 Swagger/OpenAPI？

Swagger 是一個與語言無關(guān)的規(guī)范，用于描述 REST API。Swagger 項目已捐贈給 OpenAPI 計劃，現(xiàn)在它被稱為開放 API。這兩個名稱可互換使用，但 OpenAPI 是首選。它允許計算機(jī)和人員了解服務(wù)的功能，而無需直接訪問實現(xiàn)（源代碼、網(wǎng)絡(luò)訪問、文檔）。其中一個目標(biāo)是盡量減少連接取消關(guān)聯(lián)的服務(wù)所需的工作量。另一個目標(biāo)是減少準(zhǔn)確記錄服務(wù)所需的時間。

Nswag VS Swashbuckle？

.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 客戶端代碼的方法。

為什么我在.NET core3.0中選擇NSwag呢，因為Swashbuckle目前不在維護(hù)了，而NSwag比較活躍，一直在更新，功能也很強(qiáng)大，可以完美的代替Swashbuckle.AspNetCore具體可以參考：https://github.com/aspnet/AspNetCore.Docs/issues/4258

一、利用Nswag生成Api文檔

步驟

創(chuàng)建Asp.NET?Core Api項目，并且集成NSwag

配置項目

運(yùn)行項目

創(chuàng)建Asp.NET?Core Api項目，并且集成NSwag

我們將簡單的創(chuàng)建一個ASP.NET core API項目。將其命名為“WebAPIwithSwg”?；?NETcore3.0

安裝nuget包NSwag.AspNetCore

接下來，在Startup.cs文件中配置Nswag服務(wù)和中間件。

在ConfigureServices方法中添加服務(wù)

public void ConfigureServices(IServiceCollection services)
{
services.AddControllers();
services.AddSwaggerDocument(); //注冊Swagger 服務(wù)
}

在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文檔（默認(rèn)路由文檔 /swagger/v1/swagger.json）
app.UseSwaggerUi3();//添加Swagger UI到請求管道中(默認(rèn)路由: /swagger).
}

配置項目

運(yùn)行項目

右鍵項目在瀏覽器中查看，查看swagger UI需要在url后面添加“/swagger”。本示例http://localhost:54117/swagger

二、利用NSwagStudio如何生成客戶端代碼,并且進(jìn)行測試

提供GUI界面是NSwag的一大特點，只需要下載安裝NSwagStudio，即可生成客戶端代碼。

步驟

現(xiàn)在安裝NSwagStudio

NSwagStudio配置，生成客戶端代碼

創(chuàng)建測試客戶端項目

下載安裝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”復(fù)選框，然后勾選掉 “Inject Http Client via Constructor (life cycle is managed by caller)” ，最后設(shè)置下輸出路徑 點擊生成文件（Generate Files）。步驟如下

到此客戶端代碼已經(jīng)自動生成。

查看生成的部分代碼

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(); } }

創(chuàng)建測試客戶端項目

創(chuàng)建一個控制程序項目，命名“WebApiClient”。

把自動生成的類“WeatherForecastClient”添加到客戶端項目中，然后安裝Newtonsoft

最后在Main函數(shù)中添加測試代碼，開始使用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!");
}

運(yùn)行客戶端應(yīng)用程序，進(jìn)行調(diào)用api

當(dāng)然如果需要調(diào)試api項目內(nèi)部代碼，可以設(shè)置斷點，進(jìn)入一步一步的調(diào)試

小結(jié)：NSwag 功能遠(yuǎn)不止這些，本篇文章演示了如何生成api文檔和自動生成的api客戶端代碼方便我們調(diào)試，也可以作為對應(yīng)的sdk。

參考：微軟官方文檔---https://docs.microsoft.com/zh-cn/aspnet/core/tutorials/getting-started-with-nswag?view=aspnetcore-2.2&tabs=visual-studio

總結(jié)

以上是生活随笔為你收集整理的.NET Core 3.0 使用Nswag生成Api文档和客户端代码的全部內(nèi)容，希望文章能夠幫你解決所遇到的問題。

如果覺得生活随笔網(wǎng)站內(nèi)容還不錯，歡迎將生活随笔推薦給好友。