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

阿里云2000元红包!本站用户参与享受九折优惠!

摘要 在前后端分离、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 UR L 输入你的 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> 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>(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 );
} 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

「点点赞赏,手留余香」

    还没有人赞赏,快来当第一个赞赏的人吧!
0 条回复 A 作者 M 管理员
    所有的伟大,都源于一个勇敢的开始!
欢迎您,新朋友,感谢参与互动!欢迎您 {{author}},您在本站有{{commentsCount}}条评论