ASP.NET Core WebApi使用Swagger生成api说明文档看这篇就够了

引言

在使用asp.net core 进行api开发完成后,书写api说明文档对于程序员来说想必是件很痛苦的事情吧,但文档又必须写,而且文档的格式如果没有具体要求的话,最终完成的文档则完全取决于开发者的心情。或者详细点,或者简单点。那么有没有一种快速有效的方法来构建api说明文档呢?答案是肯定的, Swagger就是最受欢迎的REST APIs文档生成工具之一!

为什么使用Swagger作为REST APIs文档生成工具

  1. Swagger 可以生成一个具有互动性的API控制台,开发者可以用来快速学习和尝试API。

  2. Swagger 可以生成客户端SDK代码用于各种不同的平台上的实现。

  3. Swagger 文件可以在许多不同的平台上从代码注释中自动生成。

  4. Swagger 有一个强大的社区,里面有许多强悍的贡献者。

asp.net core中如何使用Swagger生成api说明文档呢

  1. Swashbuckle.AspNetCore 是一个开源项目,用于生成 ASP.NET Core Web API 的 Swagger 文档。

  2. NSwag 是另一个用于将 Swagger UI 或 ReDoc 集成到 ASP.NET Core Web API 中的开源项目。 它提供了为 API 生成 C# 和 TypeScript 客户端代码的方法。

下面以Swashbuckle.AspNetCore为例为大家进行展示

Swashbuckle由哪些组成部分呢?

  • Swashbuckle.AspNetCore.Swagger:将 SwaggerDocument 对象公开为 JSON 终结点的 Swagger 对象模型和中间件。

  • Swashbuckle.AspNetCore.SwaggerGen:从路由、控制器和模型直接生成 SwaggerDocument 对象的 Swagger 生成器。 它通常与 Swagger 终结点中间件结合,以自动公开 Swagger JSON。

  • Swashbuckle.AspNetCore.SwaggerUI:Swagger UI 工具的嵌入式版本。 它解释 Swagger JSON 以构建描述 Web API 功能的可自定义的丰富体验。 它包括针对公共方法的内置测试工具。

如何使用vs2017安装Swashbuckle呢?

  • 从“程序包管理器控制台”窗口进行安装

  • 转到“视图” > “其他窗口” > “程序包管理器控制台”

  • 导航到包含 TodoApi.csproj 文件的目录

  • 请执行以下命令 ·Install-Package Swashbuckle.AspNetCore

  • 640?wx_fmt=png

  • 从“管理 NuGet 程序包”对话框中:

  • 右键单击“解决方案资源管理器” > “管理 NuGet 包”中的项目

  • 将“包源”设置为“nuget.org”

  • 在搜索框中输入“Swashbuckle.AspNetCore”

  • 从“浏览”选项卡中选择“Swashbuckle.AspNetCore”包,然后单击“安装”

  • 640?wx_fmt=png

添加并配置 Swagger 中间件

首先引入命名空间:

using Swashbuckle.AspNetCore.Swagger;

将 Swagger 生成器添加到 Startup.ConfigureServices 方法中的服务集合中:

//注册Swagger生成器,定义一个和多个Swagger 文档services.AddSwaggerGen(c =>
{     c.SwaggerDoc("v1", new Info { Title = "My API", Version = "v1" });
});

在 Startup.Configure 方法中,启用中间件为生成的 JSON 文档和 Swagger UI 提供服务:

//启用中间件服务生成Swagger作为JSON终结点app.UseSwagger();//启用中间件服务对swagger-ui,指定Swagger JSON终结点app.UseSwaggerUI(c =>
{    c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
});

启动应用,并导航到 http://localhost:<port>/swagger/v1/swagger.json。 生成的描述终结点的文档显示如下json格式。

640?wx_fmt=png

可在 http://localhost:<port>/swagger 找到 Swagger UI。 通过 Swagger UI 浏览 API文档,如下所示。

640?wx_fmt=png

要在应用的根 (http://localhost:<port>/) 处提供 Swagger UI,请将 RoutePrefix 属性设置为空字符串:

app.UseSwaggerUI(c =>
{    c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");    c.RoutePrefix = string.Empty;
});

Swagger的高级用法(自定义以及扩展)

使用Swagger为API文档增加说明信息

在 AddSwaggerGen 方法的进行如下的配置操作会添加诸如作者、许可证和说明信息等:

//注册Swagger生成器,定义一个和多个Swagger 文档services.AddSwaggerGen(c =>
{c.SwaggerDoc("v1", new Info{Version = "v1",Title = "yilezhu's API",Description = "A simple example ASP.NET Core Web API",TermsOfService = "None",Contact = new Contact{Name = "依乐祝",Email = string.Empty,Url = "http://www.cnblogs.com/yilezhu/"},License = new License{Name = "许可证名字",Url = "http://www.cnblogs.com/yilezhu/"}});
});

wagger UI 显示版本的信息如下图所示:

640?wx_fmt=png

为了防止博客被转载后,不保留本文的链接,特意在此加入本文的链接:https://www.cnblogs.com/yilezhu/p/9241261.html

为接口方法添加注释

大家先点击下api,展开如下图所示,可以没有注释啊,怎么来添加注释呢?

640?wx_fmt=png

按照下图所示用三个/添加文档注释,如下所示

/// <summary>
/// 这是一个api方法的注释
/// </summary>
/// <returns></returns>
[HttpGet]
public ActionResult<IEnumerable<string>> Get() {  
  return new string[] { "value1", "value2" }; }

然后运行项目,回到swaggerUI中去查看注释是否出现了呢

640?wx_fmt=png

还是没有出现,别急,往下看!

启用XML 注释

可使用以下方法启用 XML 注释:

  • 右键单击“解决方案资源管理器”中的项目,然后选择“属性”

  • 查看“生成”选项卡的“输出”部分下的“XML 文档文件”框

  • 640?wx_fmt=png

启用 XML 注释后会为未记录的公共类型和成员提供调试信息。如果出现很多警告信息  例如,以下消息指示违反警告代码 1591:

warning CS1591: Missing XML comment for publicly visible type or member 'TodoController.GetAll()'

如果你有强迫症,想取消警告怎么办呢?可以按照下图所示进行取消

640?wx_fmt=png

注意上面生成的xml文档文件的路径,

 注意:

1.对于 Linux 或非 Windows 操作系统,文件名和路径区分大小写。 例如,“SwaggerDemo.xml”文件在 Windows 上有效,但在 CentOS 上无效。

2.获取应用程序路径,建议采用Path.GetDirectoryName(typeof(Program).Assembly.Location)这种方式或者·AppContext.BaseDirectory这样来获取

//注册Swagger生成器,定义一个和多个Swagger 文档services.AddSwaggerGen(c =>{c.SwaggerDoc("v1", new Info{Version = "v1",Title = "yilezhu's API",Description = "A simple example ASP.NET Core Web API",TermsOfService = "None",Contact = new Contact{Name = "依乐祝",Email = string.Empty,Url = "http://www.cnblogs.com/yilezhu/"},License = new License{Name = "许可证名字",Url = "http://www.cnblogs.com/yilezhu/"}});                // 为 Swagger JSON and UI设置xml文档注释路径var basePath = Path.GetDirectoryName(typeof(Program).Assembly.Location);//获取应用程序所在目录(绝对,不受工作目录影响,建议采用此方法获取路径)var xmlPath = Path.Combine(basePath, "SwaggerDemo.xml");c.IncludeXmlComments(xmlPath);});

重新生成并运行项目查看一下注释出现了没有

640?wx_fmt=png

通过上面的操作可以总结出,Swagger UI 显示上述注释代码的 <summary> 元素的内部文本作为api大的注释!

当然你还可以将 remarks 元素添加到 Get 操作方法文档。 它可以补充 <summary> 元素中指定的信息,并提供更可靠的 Swagger UI。 <remarks> 元素内容可包含文本、JSON 或 XML。 代码如下:

 /// <summary>/// 这是一个带参数的get请求/// </summary>/// <remarks>/// 例子:/// Get api/Values/1/// </remarks>/// <param name="id">主键</param>/// <returns>测试字符串</returns>          [HttpGet("{id}")] public ActionResult<string> Get(int id) {       return $"你请求的 id 是 {id}";}

重新生成下项目,当好到SwaggerUI看到如下所示:

640?wx_fmt=png

描述响应类型

摘录自:https://www.cnblogs.com/yanbigfeg/p/9232844.html

接口使用者最关心的就是接口的返回内容和响应类型啦。下面展示一下201和400状态码的一个简单例子:

我们需要在我们的方法上添加:[ProducesResponseType(201)][ProducesResponseType(400)]

然后添加相应的状态说明:

最终代码应该是这个样子:

 /// <summary>/// 这是一个带参数的get请求/// </summary>/// <remarks>/// 例子:/// Get api/Values/1/// </remarks>/// <param name="id">主键</param>/// <returns>测试字符串</returns> /// <response code="201">返回value字符串</response>/// <response code="400">如果id为空</response>  // GET api/values/2
[HttpGet("{id}")] [ProducesResponseType(201)] [ProducesResponseType(400)]
public ActionResult<string> Get(int id){  
   return $"你请求的 id 是 {id}"; }

效果如下所示
640?wx_fmt=png

使用SwaggerUI测试api接口

下面我们通过一个小例子通过SwaggerUI调试下接口吧

  1. 点击一个需要测试的API接口,然后点击Parameters左右边的“Try it out ” 按钮

  2. 在出现的参数文本框中输入参数,如下图所示的,输入参数2

  3. 点击执行按钮,会出现下面所示的格式化后的Response,如下图所示

640?wx_fmt=png

好了,今天的在ASP.NET Core WebApi使用Swagger生成api说明文档看这篇就够了的教程就到这里了。希望能够对大家学习在ASP.NET Core中使用Swagger生成api文档有所帮助!

总结

本文从手工书写api文档的痛处说起,进而引出Swagger这款自动生成api说明文档的工具!然后通过通俗易懂的文字结合图片为大家演示了如何在一个ASP.NET Core WebApi中使用SwaggerUI生成api说明文档。最后又为大家介绍了一些ASP.NET Core 中Swagger的一些高级用法!希望对大家在ASP.NET Core中使用Swagger有所帮助!

原文地址:https://www.cnblogs.com/yilezhu/p/9241261.html

.NET社区新闻,深度好文,欢迎访问公众号文章汇总 http://www.csharpkit.com

640?wx_fmt=jpeg

本文来自互联网用户投稿,该文观点仅代表作者本人,不代表本站立场。本站仅提供信息存储空间服务,不拥有所有权,不承担相关法律责任。如若转载,请注明出处:http://www.mzph.cn/news/320988.shtml

如若内容造成侵权/违法违规/事实不符,请联系多彩编程网进行投诉反馈email:809451989@qq.com,一经查实,立即删除!

相关文章

P3201-[HNOI2009]梦幻布丁【启发式合并,链表】

正题 题目链接:https://www.luogu.com.cn/problem/P3201 题目大意 开始有nnn个布丁&#xff0c;第iii个是cic_ici​颜色的。 每次有操作 将所有颜色为xxx的布丁变为颜色yyy的。询问有多少个布丁颜色段。 解题思路 对于每次修改&#xff0c;我们可以考虑启发式合并&#xff…

【贪心】奶酪厂(jzoj 1285)

奶酪厂 题目大意&#xff1a; 有一个奶酪厂&#xff0c;每个星期&#xff08;共n个星期&#xff09;都有一定的单位生产成本和客户需求量&#xff0c;把奶酪保存一个星期每单位要s元&#xff0c;问一共花的钱最少是多少 Sample Input 4 5 88 200 89 400 97 300 91 500Sampl…

P3768 简单的数学题 [狄利克雷卷积,杜教筛,莫比乌斯反演]

简单的数学题 题目连接 https://www.luogu.org/problemnew/show/P3768 题目描述 输入一个正整数n,n≤1010n,n\le 10^{10}n,n≤1010和p,p≤1.1109p,p \le 1.1 \times 10^9p,p≤1.1109.且ppp为质数. 计算∑i1n∑j1nijgcd(i,j)\sum_{i1}^n\sum_{j1}^nijgcd(i,j)∑i1n​∑j1n​…

.NET Core微服务之基于Exceptionless实现分布式日志记录

一、Exceptionless极简介绍Exceptionless 是一个开源的实时的日志收集框架&#xff0c;它可以应用在基于 ASP.NET&#xff0c;ASP.NET Core&#xff0c;Web API&#xff0c;Web Forms&#xff0c;WPF&#xff0c;Console&#xff0c;ASP.NET MVC 等技术开发的应用程序中&#x…

P2801-教主的魔法【分块,二分】

正题 题目链接:https://www.luogu.com.cn/problem/P2801 题目大意 nnn个数字&#xff0c;要求支持 区间加上一个数字www询问一个区间内不小于www的数的个数 解题思路 考虑分块&#xff0c;对于块内我们维护一个排序后的数组&#xff0c;查询时直接在整个块中二分答案即可。修…

【多重背包】太空电梯(jzoj 1286)

太空电梯 题目大意&#xff1a; 有n&#xff08;1<n<400&#xff09;种石头&#xff0c;每种石头有它的数量c&#xff08;1<c<10&#xff09;&#xff0c;高度h&#xff08;1<h<100&#xff09;&#xff0c;可搭到的最高高度a&#xff08;1<a<40000&…

P2522 HAOI2011 Problem b [莫比乌斯反演,数论分块]

P2522 HAOI2011 题意 对于给出的n个询问&#xff0c;每次求有多少个数对(x,y)(x,y)(x,y)&#xff0c;满足a≤x≤ba≤x≤ba≤x≤b&#xff0c;c≤y≤dc≤y≤dc≤y≤d&#xff0c;且gcd(x,y)kgcd(x,y) kgcd(x,y)k&#xff0c;gcd(x,y)gcd(x,y)gcd(x,y)函数为xxx和yyy的最大公约…

.netcore 整合 log4net

1.背景前两天&#xff0c;曾经的一个同事咨询我&#xff0c;怎样将log4net以中间件的形式整合到core里边去。我不假思索的回答&#xff0c;这种问题应该有人做过吧&#xff0c;他说没有。于是&#xff0c;我去博客园搜了下&#xff0c;发现还真没有&#xff0c;全部都是传统.NE…

P5459-[BJOI2016]回转寿司【树状数组】

正题 题目链接:https://www.luogu.com.cn/problem/P5459 题目大意 nnn个数&#xff0c;求有多少个区间和在[L,R][L,R][L,R]范围内。 解题思路 显然我们做了前缀和之后&#xff0c;枚举右端点就只需要找到有多少个左端点满足在[x−R,x−L][x-R,x-L][x−R,x−L]这个范围内就好了…

【暴力】穹妹的求助

穹妹的求助 题目大意&#xff1a; 输入两个数&#xff0c;输出这两个数之间因数最多的数&#xff0c;和这个数的的因数个数 原题&#xff1a; 题目描述 由于穹妹很聪明&#xff0c;她的数学老师给她布置了一个作业&#xff0c;让她求出L到R之间不同因子数最多的那个数和这…

Asp.Net Core中利用Seq组件展示结构化日志功能

在一次.Net Core小项目的开发中&#xff0c;掌握的不够深入&#xff0c;对日志记录并没有好好利用&#xff0c;以至于一出现异常问题&#xff0c;都得跑动服务器上查看&#xff0c;那时一度怀疑自己肯定没学好&#xff0c;不然这一块日志不可能需要自己扒服务器日志来查看&…

P2633-Count on a tree【主席树,LCA】

正题 题目链接:https://www.luogu.com.cn/problem/P2633 题目大意 nnn个点的树&#xff0c;每个点有点权&#xff0c;求u∼vu\sim vu∼v的路径上第kkk小的权值&#xff0c;强制在线。 解题思路 考虑在树上维护主席树&#xff0c;我们不难发现如果sizxsiz_xsizx​表示根节点到…

P3327 约数的个数和 [约数函数性质,数论分块]

P3327 约数的个数和 题意 d(x)d(x)d(x)为约数的个数,对于每个询问,回答∑i1n∑j1md(ij)\sum_{i1}^n\sum_{j1}^md(ij)∑i1n​∑j1m​d(ij). 题解 这个题推得我头皮发麻,然后还没推出来,后来发现要做这题的先知道一个性质: d(ij)∑x∣i∑y∣j[gcd(x,y)1]d(ij)\sum_{x|i}\sum_{…

【结论】小X的矩阵

小X的矩阵 题目大意&#xff1a; 有一个nn的矩阵&#xff0c;要你执行g此操作&#xff0c;然后根据操作输出&#xff08;详情见原题&#xff09; 原题&#xff1a; 题目描述 小X最近迷上了矩阵&#xff0c;他定义了一个对于一种特殊矩阵的特征函数G。对于N∗NN*NN∗N的矩阵…

Apache SkyWalking的架构设计【译文】

Apache SkyWalking提供了一个功能强大并且很轻量级的后端。在此&#xff0c;将介绍为什么采用以下方式来设计它&#xff0c;以及它又是如何工作的。架构图对于APM而言&#xff0c;agent或SDKs仅是如何使用libs的技术细节。手动或自动的形式与架构无关&#xff0c;因此在本文中&…

P4735-最大异或和【可持久化Trie】

正题 题目链接:https://www.luogu.com.cn/problem/P4735 题目大意 nnn个数字&#xff0c;有操作 在末尾加入一个数字xxx询问[l,r][l,r][l,r]范围内的一个ppp使得ap⊕ap1⊕ap2...⊕an⊕xa_p\oplus a_{p1}\oplus a_{p2}...\oplus a_{n}\oplus xap​⊕ap1​⊕ap2​...⊕an​⊕x的…

【SPFA】桐人的约会

桐人的约会 题目大意&#xff1a; 删掉一条边&#xff0c;让一个图中的最短路最长 原题&#xff1a; 题目描述 这是一个风和日丽的日子&#xff0c;桐人和诗乃在约会。他们所在的城市共有N个街区&#xff0c;和M条道路&#xff0c;每条道路连接两个不同的街区&#xff0c;…

北京区域赛I题,Uva7676,A Boring Problem,前缀和差分

A Boring Problem 题解 其实这题不难,只要想到了前缀和差分就基本OK了. 我们要求的是第iii项的式子: F(i)(a1a2...ai)k(a2...ai)k...(ai)kF(i)(a_1a_2...a_i)^k(a2...a_i)^k...(a_i)^kF(i)(a1​a2​...ai​)k(a2...ai​)k...(ai​)k 记Sia1a2...ai,S00S_i a_1a_2...a_i,S_…

P4331-[BalticOI2004]Sequence数字序列【左偏树】

正题 题目链接:https://www.luogu.com.cn/problem/P4331 题目大意 给出一个序列aaa&#xff0c;求一个单调上升的序列bbb使得∑i1n∣ai−bi∣\sum_{i1}^n|a_i-b_i|∑i1n​∣ai​−bi​∣最小。 解题思路 巧妙的解法 首先我们让所有的ai−ia_i-iai​−i这样我们求的bbb序列就…

通俗易懂,什么是.NET?什么是.NET Framework?什么是.NET Core?

什么是.NET&#xff1f;什么是.NET Framework?本文将从上往下&#xff0c;循序渐进的介绍一系列相关.NET的概念&#xff0c;先从类型系统开始讲起&#xff0c;我将通过跨语言操作这个例子来逐渐引入一系列.NET的相关概念&#xff0c;这主要包括&#xff1a;CLS、CTS(CLI)、FCL…