.NET Core 3.0 使用Nswag生成Api文档和客户端代码

  • 2020 年 2 月 12 日
  • 筆記

摘要

在前后端分离、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呢，因为Swashbuckle目前不在维护了，而NSwag比较活跃，一直在更新，功能也很强大，可以完美的代替Swashbuckle.AspNetCore具体可以参考：https://github.com/aspnet/AspNetCore.Docs/issues/4258

一、利用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

二、利用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

VirMach 便宜 VPS

QNews

QNews