.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呢,因为Swashbuckle目前不在维护了,而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
.NET Core 3.0 使用Nswag生成Api文档和客户端代码相关推荐
- python生成api文档_sphinx生成python文档
**sphinx比较适合为Python生成文档** 1.安装sphinx ```shell pip install sphinx sphinx-autobuild sphinx_rtd_theme ` ...
- springfox源码_【开源项目】springfox-bridge:随心所欲地为非restful接口生成API文档...
一.引言 目前,利用swagger框架为restful接口编写API文档非常流行,在spring web项目中,利用springfox+swagger更是可以通过注解的方式直接进行API文档的生成,这 ...
- 干掉 Postman?测试接口直接生成API文档,这工具真香!
前几天粉丝群有小伙伴问,有啥好用的API文档工具推荐,无意间发现了一款工具,这里马不停蹄的来给大家分享一下. ShowDoc一个非常适合团队的在线API文档工具,也支持用docker自建文档服务,不过 ...
- 干掉 Postman?测试接口直接生成API文档,这个工具我爱了
前几天粉丝群有小伙伴问,有啥好用的API文档工具推荐,无意间发现了一款工具,这里马不停蹄的来给大家分享一下. ShowDoc一个非常适合团队的在线API文档工具,也支持用docker自建文档服务,不过 ...
- 使用sphinx快速为你python注释生成API文档
sphinx简介 sphinx是一种基于Python的文档工具,它可以令人轻松的撰写出清晰且优美的文档,由Georg Brandl在BSD许可证下开发.新版的Python3文档就是由sphinx生成的 ...
- knife4j是为Java MVC框架集成Swagger生成Api文档的增强解决方案
knife4j knife4j是为Java MVC框架集成Swagger生成Api文档的增强解决方案,前身是swagger-bootstrap-ui,取名kni4j是希望它能像一把匕首一样小巧,轻量, ...
- wordpress rest api 登录_Python构建RESTful网络服务[Django篇:生成API文档]
链接:https://pan.baidu.com/s/15Mo9adr4Iw2W-um7WK68jA 提取码:ux79 系列文章介绍 本系列文章将详细介绍将Django官方引导教程中的投票项目改写为R ...
- Django系列(1)-自动化生成API文档
PS: 个人深感python开发者社区氛围比安卓/ios/java差多了.不过,这也许是个机会- 前提: 本人开发环境是mac10.14.4,Python3.7.2 django-rest-swagg ...
- 浅析如何在Nancy中使用Swagger生成API文档
原文:浅析如何在Nancy中使用Swagger生成API文档 前言 上一篇博客介绍了使用Nancy框架内部的方法来创建了一个简单到不能再简单的Document.但是还有许许多多的不足. 为了能稍微完善 ...
最新文章
- 【0702作业】输出两种菱形(实心菱形和空心菱形)
- Swt/Jface中提供的dialog
- 015_视图(Views)
- 贪吃蛇程序 php,php Web程序 - 贪吃蛇学院-专业IT技术平台
- php获取用户的上5级用户
- Atitit 身份证 证件编码规范
- 【面试官系列】10个必会JavaScript高频手写题,思路和相关知识点都给你备好了,不会看不懂了
- 怎么自费出书方法步骤
- 一起学习网站开发之基于Spring boot的微信登录开发流程和知识点
- 张家界自助游(攻略)介绍!
- Python网络爬虫:下载漫画的正确姿势
- POJ 3026 Borg Maze(BFS+最小生成树)
- redis自定义lua脚本
- 你轻轻哼唱一句,都是最美的一首歌
- 人人网登录并写留言板(Requests,js逆向)
- HDU - 1465 不容易系列之一 【错排】
- ThinkPHP 入手
- 创蓝闪验一键登录(Java实现)
- 把Linux下外设的USB端口号映射到固定的名字
- 电动车铅酸电池的正确充电方法(过度充电,会导致板栅金属层变薄,容易断栅格;过度放电会导致极板硫化,活性海绵组织失效,缩短极板寿命)
热门文章
- 转:asp.net 负载平衡-Session相关
- 如何在Windows 10的地图应用程序中获取离线地图
- redhat9Linux解压gz,linux (redhat9)下subversion 的安装
- MySQL设置从库只读模式
- Windows 7 下右键发送到菜单项没了
- Nginx图片剪裁模块探究 http_image_filter_module
- python assert的作用
- 【Solidity】3.类型 - 深入理解Solidity
- cobbler工作流分析
- 【ACR2015】依那西普按需维持治疗策略有效抑制RA骨破坏进展