一、问题背景
随着技术的发展,现在的开发模式已经更多的转向了前后端分离的模式,在前后端开发的过程中,联系的方式也变成了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文件导入(具体工具用法,大家可以去看他们的官网)
源码下载:demo地址
五、总结
Swagger是一个很好的工具,并且在前后端分离开发越来越流行的情况下,在后续的开发过程中,我觉得会扮演着越来越重要的作用,目前我们公司小的项目已经准备开始使用swagger+yapi进行API的管理方式,而这篇文章也是这段时间抽空整理API管理的结果,希望可以帮助到大家,这里可能有很多不足的地方,欢迎大家拍砖,也希望可以跟大家一起进步
以上就是这篇文章的全部内容了,希望本文的内容对大家的学习或者工作具有一定的参考学习价值,如果有疑问大家可以留言交流,谢谢大家对的支持。
免责声明:本站资源来自互联网收集,仅供用于学习和交流,请遵循相关法律法规,本站一切资源不代表本站立场,如有侵权、后门、不妥请联系本站删除!
RTX 5090要首发 性能要翻倍!三星展示GDDR7显存
三星在GTC上展示了专为下一代游戏GPU设计的GDDR7内存。
首次推出的GDDR7内存模块密度为16GB,每个模块容量为2GB。其速度预设为32 Gbps(PAM3),但也可以降至28 Gbps,以提高产量和初始阶段的整体性能和成本效益。
据三星表示,GDDR7内存的能效将提高20%,同时工作电压仅为1.1V,低于标准的1.2V。通过采用更新的封装材料和优化的电路设计,使得在高速运行时的发热量降低,GDDR7的热阻比GDDR6降低了70%。
更新日志
- 凤飞飞《我们的主题曲》飞跃制作[正版原抓WAV+CUE]
- 刘嘉亮《亮情歌2》[WAV+CUE][1G]
- 红馆40·谭咏麟《歌者恋歌浓情30年演唱会》3CD[低速原抓WAV+CUE][1.8G]
- 刘纬武《睡眠宝宝竖琴童谣 吉卜力工作室 白噪音安抚》[320K/MP3][193.25MB]
- 【轻音乐】曼托凡尼乐团《精选辑》2CD.1998[FLAC+CUE整轨]
- 邝美云《心中有爱》1989年香港DMIJP版1MTO东芝首版[WAV+CUE]
- 群星《情叹-发烧女声DSD》天籁女声发烧碟[WAV+CUE]
- 刘纬武《睡眠宝宝竖琴童谣 吉卜力工作室 白噪音安抚》[FLAC/分轨][748.03MB]
- 理想混蛋《Origin Sessions》[320K/MP3][37.47MB]
- 公馆青少年《我其实一点都不酷》[320K/MP3][78.78MB]
- 群星《情叹-发烧男声DSD》最值得珍藏的完美男声[WAV+CUE]
- 群星《国韵飘香·贵妃醉酒HQCD黑胶王》2CD[WAV]
- 卫兰《DAUGHTER》【低速原抓WAV+CUE】
- 公馆青少年《我其实一点都不酷》[FLAC/分轨][398.22MB]
- ZWEI《迟暮的花 (Explicit)》[320K/MP3][57.16MB]