.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）諮詢.