ASP.NET Core Web API中使用Swagger

本节导航

  • Swagger介绍

  • 在ASP.NET CORE 中的使用swagger


  在软件开发中,管理和测试API是一件重要而富有挑战性的工作。在我之前的文章《研发团队,请管好你的API文档》 也专门阐述了通过文档管理工具,来保证API文档和代码的一致性,这样更加有助于团队的协作。

  以往我们总是通过第三方平台工具来管理我们的API文档,如eolinker。在测试方面,我们也会依赖fiddler,PostMan这样的工具。

  Swagger兼具了API文档管理和测试的功能,而且保证了代码和文档的一致性。它提供了无需任何实现逻辑的RESTfulAPI的UI表示。它允许用户在没有任何代码访问的情况下了解服务的功能,并减少创建服务文档的时间。

1 Swagger介绍

  Swagger兼具了API文档管理和测试的功能,而且保证了代码和文档的一致性。它提供了无需任何实现逻辑的RESTfulAPI的UI表示。它允许用户在没有任何代码访问的情况下了解服务的功能,并减少创建服务文档的时间。

  swagger使用swagger工具基于我们编写的服务代码生成的swagger.json文件来生成文档管理界面。此文件描述服务的功能,即服务支持多少方法,并提供有关方法参数的信息。使用这个文件,SwaggerUI生成客户机代码。下面是swagger.json文件的一个示例。

{    "swagger": "2.0",    "info": {        "version": "1.0",        "title": "My Demo API"    },    "paths": {        "/api/Values": {            "get": {                "tags": ["Values"],                "summary": "Get values",                "operationId": "Get",                "consumes": [],                "produces": ["text/plain", "application/json", "text/json"],                "parameters": [],                "responses": {                    "200": {                        "description": "Success",                        "schema": {                            "uniqueItems": false,                            "type": "array",                            "items": {                                "type": "string"                            }                        }                    }                }            },            "post": {                "tags": ["Values"],                "operationId": "Post",                "consumes": ["application/json-patch+json", "application/json", "text/json", "application/*+json"],                "produces": [],                "parameters": [{                    "name": "value",                    "in": "body",                    "required": false,                    "schema": {                        "type": "string"                    }                }],                "responses": {                    "200": {                        "description": "Success"                    }                }            }        }    },    "definitions": {}}

  在APS.NET Core Web API 中,我们可以用Swashbuckle.AspNetCore 和 NSwag这两个包来实现Swagger,而且二者都是github上开源的。此外,nswag还提供了生成typescript客户端代码的方法以及用于API的服务代码。


2 在ASP.NET CORE 中的使用swagger

  这里以Swashbuckle.AspNetCore来实现。

  以下是在ASP.net Core Web API中配置Swagger的步骤:

1. 安装Swashbuckle.AspNetCore

PM> Install-Package Swashbuckle.AspNetCore

2. 配置swagger中间件

  要将swagger middle添加到请求管道,需要在startup类的configureService方法中添加swaggergen方法。在这里,我们可以定义一个或多个swagger XML文档。

Startup.cs

// This method gets called by the runtime. Use this method to add services to the container.        public void ConfigureServices(IServiceCollection services)        {            services.AddMvc().SetCompatibilityVersion(CompatibilityVersion.Version_2_2);            services.AddSwaggerGen(c =>            {                c.SwaggerDoc("v1.0", new Info { Title = "My Demo API", Version = "1.0" });                c.IncludeXmlComments(System.IO.Path.Combine(System.AppContext.BaseDirectory, "ZhiKeCore.API.xml"));            });        }

  如果要启用这个中间件,我们还需要在startup类的configure方法中调用useswagger方法。在这里,我们还需要配置swagerendpoint来生成UI。useswagegrui将添加一个静态文件中间件来加载swager.json文件。

// This method gets called by the runtime. Use this method to configure the HTTP request pipeline.        public void Configure(IApplicationBuilder app, IHostingEnvironment env)        {            if (env.IsDevelopment())            {                app.UseDeveloperExceptionPage();            }            else            {                // The default HSTS value is 30 days. You may want to change this for production scenarios, see https://aka.ms/aspnetcore-hsts.                app.UseHsts();            }            app.UseHttpsRedirection();            app.UseMvc();            app.UseSwagger();            app.UseSwaggerUI(c =>            {                c.SwaggerEndpoint("/swagger/v1.0/swagger.json", "My Demo API (V 1.0)");            });        }

  以上是配置swagger的基本步骤,如果我们想使用Visual Studio在开发环境中启动Swagger,还需要做一点设置。选择项目-属性-Debug,修改启动浏览器(Launch Browser)的值为swagger。

640?wx_fmt=png

  当我们启动程序以后,可以看到如下界面:

640?wx_fmt=png

  正如我们在这里看到的,它对每个HTTP动词使用不同的颜色代码。当我们单击任何操作方法时,它将询问参数详细信息,当我们单击“非常”按钮时,它将向Web API发送请求。

  在测试我们的WebAPI时,Swagger只需要最少的配置即可。

  那么,如果我们想要在UI上显示代码注释应该怎么办呢?

  在.NET Core中,我们可以通过在项目属性窗口的“构建”选项卡下设置“XML文档文件”属性来获取XML注释。

640?wx_fmt=png

  默认情况下,Swagger UI不显示此文档。我们需要传递包含exmlcomments的路径。

// This method gets called by the runtime. Use this method to configure the HTTP request pipeline.       // This method gets called by the runtime. Use this method to add services to the container.        public void ConfigureServices(IServiceCollection services)        {            services.AddMvc().SetCompatibilityVersion(CompatibilityVersion.Version_2_2);            services.AddSwaggerGen(c =>            {                c.SwaggerDoc("v1.0", new Info { Title = "My Demo API", Version = "1.0" });                c.IncludeXmlComments(System.IO.Path.Combine(System.AppContext.BaseDirectory, "ZhiKeCore.API.xml"));            });        }

640?wx_fmt=png

640?wx_fmt=gif

参考

  • https://www.c-sharpcorner.com/article/test-your-asp-net-core-web-api-with-swagger/

  • http://www.zhikestreet.com/Home/Detail/6/


原文地址:https://www.cnblogs.com/lucky_hu/p/11130209.html


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

640?wx_fmt=jpeg

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

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

相关文章

【ZJOI2015】幻想乡战略游戏【点分树】【带权重心】

题意:nnn个点带边权的树,动态修改点权viv_ivi​,最小化 钦定一个点xxx 后 ∑idist(x,i)∗vi\sum\limits_{i} dist(x,i)*v_ii∑​dist(x,i)∗vi​的值。 n,q≤105n,q \leq10^5n,q≤105,度数不超过202020 限制度数的树上的一些诡异…

P4559 [JSOI2018]列队 主席树

传送门 文章目录题意:思路:题意: 给你nnn个学生以及其位置,mmm个询问,每次询问[l,r][l,r][l,r]的学生跑到[k,kr−l][k,kr-l][k,kr−l]的位置的最小总的移动距离。当然不同的学生不能站在同一位置。 n,m≤5e5,1≤ai,k≤…

C# 8.x 先睹为快

尽管 C# 8.0 还需要几个月的时间才能发布,但是 C# 8.x 的特性计划已经开始了。该计划中的特性有一些是新提出的,而另外一些则是之前在 C# 8 中考虑过的。和往常一样,这个特性列表仍可能会发生变化。如之前的一个报告所讨论的那样,…

【WC2014】紫荆花之恋【替罪羊思想】【动态点分树】【替罪羊树】

传送门 题意:有一棵开始时没有结点的树,nnn次询问,每次新加一点并给定父结点、到父亲的距离、参数rir_iri​,并询问满足dist(u,v)≤rurvdist(u,v)\leq r_ur_vdist(u,v)≤ru​rv​的点对(u,v)(u,v)(u,v)的对数。 n≤105n\leq 10^5n≤105&…

NuGet是什么?理解与使用

如果你了解python,那么它类似pip。如果你了解nodejs,那么它类似npm。如果你了解ruby,那么它类似gem。对,它就是一个包(package)管理平台,确切的说是 .net平台的包管理工具,它提供了一…

P2468 [SDOI2010]粟粟的书架 主席树 + 二分 + 二维前缀和

传送门 文章目录题意:题意:题意: 给你一个n∗mn*mn∗m的矩阵,每次询问一个矩形,左上角是(x1,y1)(x_1,y_1)(x1​,y1​),右上角是(x2,y2)(x_2,y_2)(x2​,y2​),和一个hhh,问是否能选出…

带花树学习笔记

引入 带花树解决的是一般图的最大匹配问题。 学习此算法前你需要掌握二分图匹配的匈牙利算法,至少需要知道它的思想。 理论 众所周知,二分图匹配的思想是不断地找增广路。 严谨地讲,是找到了一条简单路径,它的起点和终点都未…

你竟然没用 Nuget 构建项目?

想写这篇文章缘起于公众号文章里的一条留言:对于一个现代化的开发平台,建立一种让开发者创建,分享与使用可复用代码的机制是十分必要的。这种“可复用代码”被打包后的文件通常被称作“包”(package),对于.…

Codeforces Round #339 (Div. 1) D. Kingdom and its Cities 虚树 + dp

传送门 文章目录题意:思路:题意: n≤1e5,∑k≤1e5,q≤1e5n\le1e5,\sum k\le1e5,q\le1e5n≤1e5,∑k≤1e5,q≤1e5。 思路: 经过分析,外敌占领的城市只有可能是两点的lcalcalca或者两点之间任意一点,是哪个点…

小白开学Asp.Net Core《四》 —— 使用AspectCore-Framework

小白开学Asp.Net Core《四》—— 使用AspectCore-Framework一、AspectCore-Framework说AspectCore-Framework不得不先谈谈的AOP,AOP:在软件业,AOP为Aspect Oriented Programming的缩写,意为:面向切面编程,通…

【WC2016】挑战NPC 【带花树】【建图】

传送门 题意:有nnn个球和mmm个筐,每个筐最多放333个球,每个球只能放入特定的一些筐中,在题中给出。构造一种放球的方案使得nnn个球都被放在某个筐中且 球的个数不超过111 的筐的数量尽量大。 m≤100,n≤3mm\leq 100,n\leq 3mm≤1…

P4103 [HEOI2014]大工程 虚树 + dp

传送门 文章目录题意:思路:题意: 思路: 简化一下题意就是求树上给定点集中每两个点之间的距离之和,相距最远的点,相距最近的点。 对于距离和我们统计一下边的贡献就好啦,边两头的sizesizesize乘…

【翻译】Keras.NET简介 - 高级神经网络API in C#

用C#,远离996Keras.NETKeras.NET是一个高级神经网络API,它使用C#编写,并带有Python绑定,可以在Tensorflow、CNTK或Theano上运行。其关注点是实现快速实验。因为做好研究的关键是:能在尽可能短的时间内从一个想法发展出…

TIOBE 6月排行:C# 以微弱的优势超过了 Visual Basic .NET 的排名,再次进入 TOP 5

月经贴警告……TIOBE 编程语言排行榜 7 月更新已公布,排名前十的分别是:Java, C, Python, C, C#, Visual Basic .NET, JavaScript, PHP, SQL 和汇编语言。和上个月的不同之处主要是 C# 以微弱的优势超过了 Visual Basic .NET 的排名,再次进入…

ETT学习笔记

ETT(Eular Tour Tree)是一种维护有根树的数据结构,支持以下操作 修改一个点的点权子树修改单点查询点到根路径查询修改一个点的父亲 据说可以支持换根,但用的不多而且据说很难写,所以似乎失传了( 其实没…

Codeforces Round #635 (Div. 2) D. Xenia and Colorful Gems 暴力 + 二分

传送门 文章目录题意:思路:题意: 给你三个数组a,b,ca,b,ca,b,c,让你从每个数组中选择一个数x,y,zx,y,zx,y,z,使得(x−y)2(x−z)2(y−z)2(x-y)^2(x-z)^2(y-z)^2(x−y)2(x−z)2(y−z)2最小,求这个最小值。 …

用.NET Core实现一个类似于饿了吗的简易拆红包功能

需求说明以前很讨厌点外卖的我,最近中午经常点外卖,因为确实很方便,提前点好餐,算准时间,就可以在下班的时候吃上饭,然后省下的那些时间就可以在中午的时候多休息一下了。点餐结束后,会有一个好…

【POI2011】LIZ-Lollipop 【构造】

传送门 题意:给一个长度为nnn的只有111和222的序列,多次询问给定xxx构造或判断无法构造一个区间和为xxx 注意到111和222实质上是改不改变奇偶性,所以往这上面考虑 我们发现如果一个区间[L,R][L,R][L,R]和为x(x>2)x(x>2)x(x>2),我…

kubernetes实战篇之helm示例yaml文件文件详细介绍

前面完整示例里,我们主要讲解helm打包,部署,升级,回退等功能,关于这里面的文件只是简单介绍,这一节我们详细介绍一下这里面的文件,以方便我们参照创建自己的helm chart.Helm Chart 结构Chart 目录结构mychart/ Chart.yaml LICENSE README.md values.yaml requirements.yam…

P4309 [TJOI2013]最长上升子序列 平衡树 + dp

传送门 文章目录题意:思路:题意: 思路: 注意到一个很关键的条件,每次插入iii,而iii是递增的,也就是说插入iii之后只会从前面的最大值转移过来,所以我们现在只需要维护插入操作即可&…