.NET Core使用swagger进行API接口文档管理

一、问题背景

　　随着技术的发展，现在的开发模式已经更多的转向了前后端分离的模式，在前后端开发的过程中，联系的方式也变成了API接口，但是目前项目中对于API的管理很多时候还是通过手工编写文档，每次的需求变更只要涉及到接口的变更，文档都需要进行额外的维护，如果有哪个小伙伴忘记维护，很多时候就会造成一连续的问题，那如何可以更方便的解决API的沟通问题？Swagger给我们提供了一个方式，由于目前主要我是投入在.NET Core项目的开发中，所以以.NET Core作为示例

二、什么是Swagger

　　Swagger可以从不同的代码中，根据注释生成API信息，swagger拥有强大的社区，并且对于各种语言都支持良好，有很多的工具可以通过swagger生成的文件生成API文档

三、.NET Core中使用

　　.NET Core中使用首先要用nuget引用Swashbuckle.AspNetCore，在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();

            services.AddSwaggerGen(c =>

            {

                c.SwaggerDoc("v1", new Info { Title = "Hello", Version = "v1" });

                var basePath = PlatformServices.Default.Application.ApplicationBasePath;

                var xmlPath = Path.Combine(basePath, "WebApplication2.xml");

                c.IncludeXmlComments(xmlPath);

            });

            services.AddMvcCore().AddApiExplorer();

        }


        // 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();

            }


            app.UseMvcWithDefaultRoute();

            app.UseSwagger(c =>

            {

            });

            app.UseSwaggerUI(c =>

            {

                c.ShowExtensions();

                c.ValidatorUrl(null);

                c.SwaggerEndpoint("/swagger/v1/swagger.json", "test V1");

            });

        }

以上部分为加载swagger的代码，位于startup.cs中，下面是controller代码：

using System;

using System.Collections.Generic;

using System.Linq;

using System.Threading.Tasks;

using Microsoft.AspNetCore.Mvc;


namespace WebApplication2.Controllers

{

    /// <summary>

    /// 测试信息

    /// </summary>

    [Route("api/[controller]/[action]")]

    public class ValuesController : Controller

    {

        /// <summary>

        /// 获取所有信息

        /// </summary>

        /// <returns></returns>

        [HttpGet]

        public IEnumerable<string> Get()

        {

            return new string[] { "value1", "value2" };

        }

        /// <summary>

        /// 根据ID获取信息

        /// </summary>

        /// <param name="id"></param>

        /// <returns></returns>

        // GET api/values/5

        [HttpGet("{id}")]

        public string Get(int id)

        {

            return "value";

        }

        /// <summary>

        /// POST了一个数据信息

        /// </summary>

        /// <param name="value"></param>

        // POST api/values

        [HttpPost]

        public void Post([FromBody]string value)

        {

        }

        /// <summary>

        /// 根据ID put 数据

        /// </summary>

        /// <param name="id"></param>

        /// <param name="value"></param>

        // PUT api/values/5

        [HttpPut("{id}")]

        public void Put(int id, [FromBody]string value)

        {

        }

        /// <summary>

        /// 根据ID删除数据

        /// </summary>

        /// <param name="id"></param>

        // DELETE api/values/5

        [HttpDelete("{id}")]

        public void Delete(int id)

        {

        }

        /// <summary>

        /// 复杂数据操作

        /// </summary>

        /// <param name="id"></param>

        // DELETE api/values/5

        [HttpPost]

        public namevalue test(namevalue _info)

        {

            return _info;

        }

    }


    public class namevalue

    {

        /// <summary>

        /// name的信息

        /// </summary>

        public String name { get; set; }

        /// <summary>

        /// value的信息

        /// </summary>

        public String value { get; set; }

    }

}

接下来我们还需要在生成中勾上XML生成文档，如图所示

　　接下去我们可以运行起来了，调试，浏览器中输入http://localhost:50510/swagger/，这里端口啥的根据实际情况来，运行效果如下图所示：

可以看到swagger将方法上的注释以及实体的注释都抓出来了，并且显示在swaggerui，整体一目了然，并且可以通过try it按钮进行简单的调试，但是在具体项目中，可能存在需要将某些客户端信息通过header带到服务中，例如token信息，用户信息等（我们项目中就需要header中带上token传递到后端），那针对于这种情况要如何实现呢？可以看下面的做法

// This method gets called by the runtime. Use this method to add services to the container.

        public void ConfigureServices(IServiceCollection services)

        {

            services.AddMvc();

            services.AddSwaggerGen(c =>

            {

                c.SwaggerDoc("v1", new Info { Title = "Hello", Version = "v1" });

                var basePath = PlatformServices.Default.Application.ApplicationBasePath;

                var xmlPath = Path.Combine(basePath, "WebApplication2.xml");

                c.IncludeXmlComments(xmlPath);

                c.OperationFilter<AddAuthTokenHeaderParameter>();

            });

            services.AddMvcCore().AddApiExplorer();

        }


    public class AddAuthTokenHeaderParameter : IOperationFilter

    {


        public void Apply(Operation operation, OperationFilterContext context)

        {


            if (operation.Parameters == null)

            {

                operation.Parameters = new List<IParameter>();

            }

            operation.Parameters.Add(new NonBodyParameter()

            {

                Name = "token",

                In = "header",

                Type = "string",

                Description = "token认证信息",

                Required = true

            });

        }

    }

我们在ConfigureServices添加了OperationFilter<AddAuthTokenHeaderParameter>()，通过这种方式我们可以在swagger中显示token的header，并且进行调试（如图所示），AddAuthTokenHeaderParameter 的apply的属性context中带了controller以及action的各种信息，可以配合实际情况使用

 四、与其他API管理工具结合

　　swagger强大的功能以及社区的力量，目前很多的API管理工具都支持YApi，目前我们使用的是由去哪儿开源的YApi，从图中可以看到YApi支持导入swagger生成的JSON文件，除该工具 之外DOClever（开源）也是一个不错的API管理工具，也支持Swagger文件导入（具体工具用法，大家可以去看他们的官网）

五、总结

　　Swagger是一个很好的工具，并且在前后端分离开发越来越流行的情况下，在后续的开发过程中，我觉得会扮演着越来越重要的作用，目前我们公司小的项目已经准备开始使用swagger+yapi进行API的管理方式，而这篇文章也是这段时间抽空整理API管理的结果，希望可以帮助到大家，这里可能有很多不足的地方，欢迎大家拍砖，也希望可以跟大家一起进步

原文地址: https://www.cnblogs.com/OMango/p/8460092.html

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

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

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

相关文章

CF451E-Devu and Flowers【组合计数,容斥】

CF451E-Devu and Flowers【组合计数,容斥】

正题 题目链接:https://www.luogu.org/problem/CF451E 题目大意 长度为nnn的序列aia_iai​&#xff0c;有如下要求 ai∈[0...xi]a_i\in[0...x_i]ai​∈[0...xi​]∑i1nais\sum_{i1}^na_is∑i1n​ai​s 求序列个数。 解题思路 考虑容斥&#xff0c;这样我们就可以将条件转换…
阅读更多...
SpringCloud Ribbon（四）之全局配置与服务配置

SpringCloud Ribbon（四）之全局配置与服务配置

一、Ribbon全局配置 RibbonClients注解配置导入全局Ribbon客户端默认设置 public class GlobalRibbonConfig {//负载均衡策略Beanpublic IRule rule() {return new MicroServiceLoadBalanceRule();}//负载均衡器Beanpublic <E extends Server> ILoadBalancer loadBalan…
阅读更多...
.NET下使用socket.io随笔记录

.NET下使用socket.io随笔记录

一、问题背景目前公司在互联网产品上需要程序与前端部分要进行一个实时交互&#xff0c;在进行一定程度上的选型后&#xff0c;决定使用socket.io框架进行一个实践&#xff0c;算是公司的一个新的 尝试&#xff0c;也算是给自己增加增长见闻&#xff0c;由于我是做后端以及桌面…
阅读更多...
bzoj2111,P2606-[ZJOI2010]排列计数【Lucas,组合计数,dp】

bzoj2111,P2606-[ZJOI2010]排列计数【Lucas,组合计数,dp】

正题 题目链接: https://www.lydsy.com/JudgeOnline/problem.php?id2111 https://www.luogu.org/problem/P2606 题目大意 长为nnn的序列PPP&#xff0c;然后要求Pi>P⌊i2⌋P_i>P_{\lfloor \frac{i}{2}\rfloor}Pi​>P⌊2i​⌋​。求排列个数。 解题思路 若用iii连向…
阅读更多...
SpringCloud Ribbon（五）之服务实例列表ServerList

SpringCloud Ribbon（五）之服务实例列表ServerList

一、服务实例列表ServerList 服务实例列表&#xff08;ServerList&#xff09;为负载均衡器&#xff08;Loadbalancer&#xff09;提供服务的可用实例列表。 负载均衡器&#xff08;Loadbalancer&#xff09;通过服务实例列表&#xff08;ServerList&#xff09;从注册中心&a…
阅读更多...
超级简便的容器化部署工具（使用 ASP.NET Core 演示）

超级简便的容器化部署工具（使用 ASP.NET Core 演示）

Docker 改变了我们部署网站的方式&#xff0c;从原先的手动编译打包上传&#xff0c;到现在的构建镜像然后推送部署&#xff0c;让我们在配置环境上所花费的时间大大减少了。不仅如此&#xff0c;通过一系列相关的工具配合&#xff0c;可以很轻松的实现 CI、CD。本文即将介绍的…
阅读更多...
学习手记(2019/7/05~2019/8/31)——快乐暑假

学习手记(2019/7/05~2019/8/31)——快乐暑假

文章目录二分答案的作用堆和区间很糙ddp线段树合并网络流结论の1树上莫队对角线与GCD区间与扫描线与方案数欧拉欧拉*1斯坦纳树切比雪夫距离二分匹配结论の1min-max容斥计算几何の -1二分答案的作用 求最大值最小ororor最小值最大将求值问题转换为判断问题在判断问题之间相互转…
阅读更多...
SpringCloud Ribbon（六）之服务实例过滤器ServerListFilter

SpringCloud Ribbon（六）之服务实例过滤器ServerListFilter

一、服务实例过滤器ServerListFilter 服务实例过滤器&#xff08;ServerListFilter&#xff09;为负载均衡器&#xff08;Loadbalancer&#xff09;提供从服务实例列表&#xff08;ServerList&#xff09;获取的服务实例过滤出符合要求的服务实例。 负载均衡器&#xff08;Lo…
阅读更多...
听说你开发.NET还在用VS，小哥哥给你推荐全平台的Rider

听说你开发.NET还在用VS，小哥哥给你推荐全平台的Rider

前言.NET平台的开发一直都只能使用Visual Studio来开发&#xff0c;自从dotnet core 发布后不久&#xff0c;jetbrains 发布了Rider预览版&#xff0c;到目前为止的正式版2017.3.1。博主都使用过&#xff0c;因为博主的主力开发语言是C#&#xff0c;所以一直以来被捆绑到Window…
阅读更多...
jzoj6293-迷宫【ddp,线段树,矩阵乘法】

jzoj6293-迷宫【ddp,线段树,矩阵乘法】

正题 题目大意 一个n∗mn*mn∗m的迷宫&#xff0c;不能往左走&#xff0c;有墙&#xff0c;每次修改一个点或询问两个点之间的最短距离。 解题思路 考虑到nnn的值很小&#xff0c;所以我们可以用矩阵转移&#xff0c;然后要求支持修改和查询所以我们考虑ddpddpddp。 我们可以…
阅读更多...
Scala与Java差异（六）之类定义

Scala与Java差异（六）之类定义

一、类定义 &#xff08;1&#xff09;定义类&#xff0c;包含field以及方法 class ScalaClass {private var field "one"def aMethod() { print("field : " field ) } def getField field } &#xff08;2&#xff09;调用对象方法 val scalaCla…
阅读更多...
jzoj6297-世界第一的猛汉王【切比雪夫距离,扫描线】

jzoj6297-世界第一的猛汉王【切比雪夫距离,扫描线】

正题 题目大意 有若干个红点和蓝点&#xff0c;对于每一对红点和蓝点&#xff0c;若距离大于DDD则蓝点压制红点&#xff0c;否则红点压制蓝点。然后红点和蓝点之间也有不定的压制关系。 求有多少个三角要求AAA压制BBB&#xff0c;BBB压制CCC&#xff0c;CCC压制AAA且至少包含…
阅读更多...
给Ocelot做一个Docker 镜像

给Ocelot做一个Docker 镜像

写在前面在微服务架构中&#xff0c;ApiGateway起到了承前启后&#xff0c;不仅可以根据客户端进行分类&#xff0c;也可以根据功能业务进行分类&#xff0c;而且对于服务调用服务也起到了很好的接口作用。目前在各个云端中&#xff0c;基本上都提供了ApiGateway的功能&#xf…
阅读更多...
Spark SQL（一）之简介

Spark SQL（一）之简介

Spark SQL是用于结构化数据处理的Spark模块。与基本的Spark RDD API不同&#xff0c;Spark SQL提供的接口为Spark提供了有关数据结构和正在执行的计算的更多信息。在内部&#xff0c;Spark SQL使用这些额外的信息来执行额外的优化。 与Spark SQL交互的方法有多种&#xff0c;包…
阅读更多...
hdu4336-Card Collector【min-max容斥,期望概率】

hdu4336-Card Collector【min-max容斥,期望概率】

正题 题目链接:http://acm.hdu.edu.cn/showproblem.php?pid4336 题目大意 每次获得第iii张牌的概率为pip_ipi​(每次只能获得一张)&#xff0c;期望多少回合后获得所有牌。 解题思路 min−maxmin-maxmin−max容斥:max{S}∑T⊆S(−1)∣T∣−1min{T}max\{S\}\sum_{T\subseteq …
阅读更多...
.NET Core UI框架Avalonia

.NET Core UI框架Avalonia

.NET Core UI框架Avalonia&#xff0c;Avalonia是一个基于WPF XAML的跨平台UI框架&#xff0c;并支持多种操作系统&#xff1a;Windows&#xff08;.NET Framework&#xff0c;.NET Core&#xff09;&#xff0c;Linux&#xff08;GTK&#xff09;&#xff0c;MacOS&#xff0c…
阅读更多...
Spark SQL（二）之DataSet操作

Spark SQL（二）之DataSet操作

一、创建DataSet 使用SparkSession&#xff0c;应用程序可以从现有的RDD&#xff0c;Hive表的或Spark数据源创建DataFrame 。 &#xff08;1&#xff09;基于JSON的内容创建一个DataFrame //hdfs Dataset<Row> df spark.read().json("hdfs://master:9000/test.j…
阅读更多...
jzoj6296-投票【期望dp,贪心】

jzoj6296-投票【期望dp,贪心】

正题 题目大意 nnn个人&#xff0c;第iii投票的概率是pip_ipi​&#xff0c;选择kkk个求最大的平票概率。 解题思路 我们显然要让kkk人中一半投票的概率大&#xff0c;一半投票的概率小。 所以我们可以先进行排序&#xff0c;这样我们发现答案一定是选取一段前缀和一段后缀。…
阅读更多...
揽货最短路径解决方案算法 - C# 蚁群优化算法实现

揽货最短路径解决方案算法 - C# 蚁群优化算法实现

需求为&#xff08;自己编的&#xff0c;非实际项目&#xff09;&#xff1a;某配送中心进行揽货&#xff0c;目标客户数为50个客户&#xff0c;配送中心目前的运力资源如下&#xff1a;现有车辆5台单台运力最大行驶距离200千米单台运力最大载重公斤1吨问&#xff1a;运力怎样走…
阅读更多...
Spark SQL（三）之视图与执行SQL

Spark SQL（三）之视图与执行SQL

一、视图与sql执行 SparkSession能够以编程方式运行SQL查询并返回结果Dataset<Row> Dataset<Row> df spark.read().json("hdfs://master:9000/test.json"); df.createOrReplaceTempView("man");Dataset<Row> sqlDF spark.sql("…
阅读更多...
最新文章

Copyright @ 2022~2023