.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
一、利用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_ == "")
{
var objectResponse_ = await ReadObjectResponseAsync<System.Collections.Generic.ICollection<WeatherForecast>>(response_, headers_).ConfigureAwait(false);
return objectResponse_.Object;
}
else
if (status_ != "" && status_ != "")
{
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文档和客户端代码的更多相关文章
- ASP.NET Core 3.0 WebApi中使用Swagger生成API文档简介
参考地址,官网:https://docs.microsoft.com/zh-cn/aspnet/core/tutorials/getting-started-with-swashbuckle?view ...
- .Net Core 3.1 WebApi使用Swagger生成Api文档
用swagger生成Api文档 1.安装Swashbuckle.AspNetCore 右键单击"解决方案资源管理器" > "管理 NuGet 包"中的项目 ...
- asp.net core使用Swashbuckle.AspNetCore(swagger)生成接口文档
asp.net core中使用Swashbuckle.AspNetCore(swagger)生成接口文档 Swashbuckle.AspNetCore:swagger的asp.net core实现 项 ...
- Codeigniter项目使用phpDocumentor生成api文档
前言 运行环境: vagrant 2.2.4 virtualbox 6.0 box bento/ubuntu-16.04 (Apache 2.4.18 + Mysql 5.7.26 + PHP 5.6 ...
- 利用sphinx为python项目生成API文档
sphinx可以根据python的注释生成可以查找的api文档,简单记录了下步骤 1:安装 pip install -U Sphinx 2:在需要生成文档的.py文件目录下执行sphinx-apido ...
- 使用bee自动生成api文档
beego中的bee工具可以方便的自动生成api文档,基于数据库字段,自动生成golang版基于beego的crud代码,方法如下: 1.进入到gopath目录的src下执行命令: bee api a ...
- 试试使用 eolinker 扫描 GitLab 代码注释自动生成 API 文档?
前言: 一般写完代码之后,还要将各类参数注解写入API文档,方便后续进行对接和测试,这个过程通常都很麻烦,如果有工具可以读取代码注释直接生成API文档的话,那会十分方便. 此前一直都是在使用eolin ...
- SpringBoot系列: 使用 Swagger 生成 API 文档
SpringBoot非常适合开发 Restful API程序, 我们都知道为API文档非常重要, 但要维护好难度也很大, 原因有: 1. API文档如何能被方便地找到? 以文件的形式编写API文档都有 ...
- 使用sphinx快速为你python注释生成API文档
sphinx简介sphinx是一种基于Python的文档工具,它可以令人轻松的撰写出清晰且优美的文档,由Georg Brandl在BSD许可证下开发.新版的Python3文档就是由sphinx生成的, ...
随机推荐
- 深入理解JavaScript中的作用域、作用域链和闭包
版权声明:本文为博主原创文章,遵循 CC 4.0 BY-SA 版权协议,转载请附上原文出处链接和本声明.本文链接:https://blog.csdn.net/qappleh/article/detai ...
- 09 python学习笔记-操作excel(九)
python操作excel使用xlrd.xlwt和xlutils模块,xlrd模块是读取excel的,xlwt模块是写excel的,xlutils是用来修改excel的.这几个模块可以使用pip安装, ...
- 【Go】高效截取字符串的一些思考
原文链接:https://blog.thinkeridea.com/201910/go/efficient_string_truncation.html 最近我在 Go Forum 中发现了 [SOL ...
- 使用 pdf.js 跨域问题的处理方法1
在<使用 pdf.js 在网页中加载 pdf 文件>中详细介绍了 pdf.js 的使用与集成网页开发的基本方法.展示效果如下图: 站点的目录为 http://localhost:8033/ ...
- label 标签的 for 属相
我的github iSAM2016 一开始学html 标签的时候,知道有label 这个标签的,但是并没有注意到他的for 属性的作用,看一下MDN的介绍 for 可标记的 form相关元素的ID,在 ...
- 关于javascript闭包的最通俗易懂的理解
这两天在研究闭包,网上一通找,有牛人写的帖子,有普通人写的帖子,但是大多没戳中本小白所纠结的点,而且大多插入了立即执行函数,其实根本不需要的,反而让人产生了误解.这里我用我的方式讲解一下闭包. 1.目 ...
- SpringBoot与热部署整合(五)
一 Idea pom.xml <dependency> <groupId>org.springframework.boot</groupId> <artifa ...
- 使用Bind提供域名解析服务(正向解析)
小知识: 一般来讲域名比IP地址更加的有含义.也更容易记住,所以通常用户更习惯输入域名来访问网络中的资源,但是计算机主机在互联网中只能通过IP识别对方主机,那么就需要DNS域名解析服务了. DNS域名 ...
- 一张图牢记vim常用命令
1.示例(前提要切到命令状态) ^ 光标移动到行首 $ 光标移动到行尾 set nu 显示行号 :%s/foo/bar/g 会在全局范围(%)查找foo并替换为bar,所有出现都会被替换(g) 参 ...
- 机器学习之scikit-learn库
前面讲到了,这个库适合学习,轻量级,所以先学它. 安装就不讲了,简单.不过得先安装numpy和pandas库才能安装scikit-learn库. 如果安装了anaconda得话,会自带有这个库. -- ...