使用Swagger生成WebApi接口文档

1.前言

从进入公司以来，一直都是在做WebApi接口，在刚开始的时候还没有认识到API文档的重要性，仅仅是因为别人说它很重要，通过一段时间的接口开发之后，自己越发认识到一个规范的接口文档的重要性。从一开始使用Word来写API文档，但是存在更新的难题，后台转到有道云笔记，效果还是很不理想，再到后来知道VisualStudio其实是可以自动生成API文档的，而我们的项目中也有用到这种方式的变种（同事使用jQuery根据xml文档生成的），不过貌似Swagger使用的也是根据VS的xml文档来生成API文档，不过swagger的功能更加强大。

2.安装Swagger

一般来说安装程序都有两种方式，一种是在NuGet包管理器，一种是NuGet程序台命令。
* 右键点击解决方案->管理解决方案的NuGet程序包->搜索swaggerui->安装Swashbuckle
* Install-Package Swashbuckle

3.配置Swagger

配置教程来源于博客园,出处https://www.cnblogs.com/webenh/p/7513090.html

1.去除注释,获取XML文档

安装完成之后会在项目目录 App_Start 文件夹下生成一个 SwaggerConfig.cs 配置文件，用于配置 SwaggerUI 相关展示行为。将代码里面的无用注释去除（为了简洁）。
在方法体内插入如下代码:
c.IncludeXmlComments(GetXmlCommentsPath(thisAssembly.GetName().Name));

.EnableSwagger(c =>
                    {
                        //文档版本
                        c.SingleApiVersion("v1", "MyWeAPI");
                        //获取xml文件
                        c.IncludeXmlComments(GetXmlCommentsPath(thisAssembly.GetName().Name));                     
                    })

添加如下方法：

/// <summary>
/// 获取VisualStudio产生的XML文档位置
/// </summary>
/// <param name="name"></param>
/// <returns></returns>
protected static string GetXmlCommentsPath(string name)
{
 return string.Format(@"{0}\bin\{1}.XML", AppDomain.CurrentDomain.BaseDirectory, name);
}

紧接着你在此Web项目属性生成选卡中勾选 “XML 文档文件”，编译过程中生成类库的注释文件

2.添加HTTP Header

首先我们需要创建一个 IOperationFilter 接口的类。IOperationFilter

using System;
using System.Collections.Generic;
using System.Linq;
using System.Web;
using System.Web.Http;
using System.Web.Http.Description;
using System.Web.Http.Filters;
using Swashbuckle.Swagger;

namespace OnlineAPI.Utility
{
    public class HttpHeaderFilter : IOperationFilter
    {
        public void Apply(Operation operation, SchemaRegistry schemaRegistry, ApiDescription apiDescription)
        {
            if (operation.parameters == null) operation.parameters = new List<Parameter>();
            var filterPipeline = apiDescription.ActionDescriptor.GetFilterPipeline();
            //判断是否添加权限过滤器
            var isAuthorized = filterPipeline.Select(filterInfo => filterInfo.Instance).Any(filter => filter is IAuthorizationFilter);
            //判断是否允许匿名方法
            var allowAnonymous = apiDescription.ActionDescriptor.GetCustomAttributes<AllowAnonymousAttribute>().Any();
            if (isAuthorized && !allowAnonymous)
            {
                operation.parameters.Add(new Parameter
                {
                    name = "access-key",
                    @in = "header",
                    description = "用户访问Key",
                    required = false,
                    type = "string"
                });
            }
        }
    }
}

在配置方法类中添加注册代码:

 GlobalConfiguration.Configuration
                .EnableSwagger(c =>
                    {
                        //文档版本
                        c.SingleApiVersion("v1", "MyWeAPI");

                        //获取xml文件
                        c.IncludeXmlComments(GetXmlCommentsPath(thisAssembly.GetName().Name));

                        //请求头配置
                        c.OperationFilter<HttpHeaderFilter>();
                    })
                .EnableSwaggerUi(c =>
                    {

                    });

然后再Controller或者Action上添加过滤器:

[AccessKey]

3.上传文件参数

SwaggerUI 有上传文件的功能和添加自定义HTTP Header 做法类似，只是我们通过特殊的设置来标示API具有上传文件的功能

using System;
using System.Collections.Generic;
using System.Linq;
using System.Web;
using System.Web.Http.Description;
using Swashbuckle.Swagger;

namespace OnlineAPI.Utility
{
    /// <summary>
    /// 
    /// </summary>
    public class UploadFilter : IOperationFilter
    {

        /// <summary>
        ///     文件上传
        /// </summary>
        /// <param name="operation"></param>
        /// <param name="schemaRegistry"></param>
        /// <param name="apiDescription"></param>
        public void Apply(Operation operation, SchemaRegistry schemaRegistry, ApiDescription apiDescription)
        {
            if (!string.IsNullOrWhiteSpace(operation.summary) && operation.summary.Contains("upload"))
            {
                operation.consumes.Add("application/form-data");
                operation.parameters.Add(new Parameter
                {
                    name = "file",
                    @in = "formData",
                    required = true,
                    type = "file"
                });
            }
        }
    }
}

添加注册配置

 GlobalConfiguration.Configuration
                .EnableSwagger(c =>
                    {
                        //文档版本
                        c.SingleApiVersion("v1", "MyWeAPI");

                        //获取xml文件
                        c.IncludeXmlComments(GetXmlCommentsPath(thisAssembly.GetName().Name));

                        //请求头配置
                        c.OperationFilter<HttpHeaderFilter>();

                        //上传文件配置
                        c.OperationFilter<UploadFilter>();
                    })
                .EnableSwaggerUi(c =>
                    {

                    });