.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

1、利用Nswag生成Api文檔

步驟

1. 建立Asp.NET Core Api項目，而且集成NSwag

2. 配置項目

3. 運行項目

建立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

2、利用NSwagStudio如何生成客戶端代碼,而且進行測試

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

步驟

1. 如今安裝NSwagStudio

2. NSwagStudio配置，生成客戶端代碼

3. 建立測試客戶端項目

下載安裝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

原文出處：https://www.cnblogs.com/chengtian/p/11946950.html