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

1、问题背景

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

2、什么是Swagger

　　Swagger能够从不一样的代码中，根据注释生成API信息，swagger拥有强大的社区，而且对于各类语言都支持良好，有不少的工具能够经过swagger生成的文件生成API文档

3、.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的各类信息，能够配合实际状况使用

 

 4、与其余API管理工具结合

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

5、总结

　　Swagger是一个很好的工具，而且在先后端分离开发愈来愈流行的状况下，在后续的开发过程当中，我以为会扮演着愈来愈重要的做用，目前咱们公司小的项目已经准备开始使用swagger+yapi进行API的管理方式，而这篇文章也是这段时间抽空整理API管理的结果，但愿能够帮助到你们，这里可能有不少不足的地方，欢迎你们拍砖，也但愿能够跟你们一块儿进步

 

　　demo地址 

 

做者： Mango

出处： http://www.cnblogs.com/OMango/

关于本身：专一.Net桌面开发以及Web后台开发，开始接触微服务、docker等互联网相关

本文版权归做者和博客园共有，欢迎转载，但未经做者赞成必须保留此段声明，且在文章页面明显位置给出, 原文连接 若有问题， 可邮件（hongjb@yizit.com）咨询.