一、问题背景

随着技术的发展,现在的开发模式已经更多的转向了前后端分离的模式,在前后端开发的过程中,联系的方式也变成了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生成文档,如图所示

.NET Core利用swagger进行API接口文档管理的方法详解

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

.NET Core利用swagger进行API接口文档管理的方法详解

可以看到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的各种信息,可以配合实际情况使用

.NET Core利用swagger进行API接口文档管理的方法详解

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

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

.NET Core利用swagger进行API接口文档管理的方法详解

源码下载:demo地址

五、总结

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

以上就是这篇文章的全部内容了,希望本文的内容对大家的学习或者工作具有一定的参考学习价值,如果有疑问大家可以留言交流,谢谢大家对的支持。

华山资源网 Design By www.eoogi.com
广告合作:本站广告合作请联系QQ:858582 申请时备注:广告合作(否则不回)
免责声明:本站资源来自互联网收集,仅供用于学习和交流,请遵循相关法律法规,本站一切资源不代表本站立场,如有侵权、后门、不妥请联系本站删除!
华山资源网 Design By www.eoogi.com

稳了!魔兽国服回归的3条重磅消息!官宣时间再确认!

昨天有一位朋友在大神群里分享,自己亚服账号被封号之后居然弹出了国服的封号信息对话框。

这里面让他访问的是一个国服的战网网址,com.cn和后面的zh都非常明白地表明这就是国服战网。

而他在复制这个网址并且进行登录之后,确实是网易的网址,也就是我们熟悉的停服之后国服发布的暴雪游戏产品运营到期开放退款的说明。这是一件比较奇怪的事情,因为以前都没有出现这样的情况,现在突然提示跳转到国服战网的网址,是不是说明了简体中文客户端已经开始进行更新了呢?