如何使 WebAPI 自動生成漂亮又實用在線API文檔

1.前言

1.1 SwaggerUI

SwaggerUI 是一個簡單的Restful API 測試和文檔工具。簡單、漂亮、易用（官方demo）。通過讀取JSON 配置顯示API. 項目本身僅僅也只依賴一些 html,css.js靜態文件. 你可以幾乎放在任何Web容器上使用。

1.2 Swashbuckle

Swashbuckle 是.NET類庫,可以將WebAPI所有開放的控制器方法生成對應SwaggerUI的JSON配置。再通過SwaggerUI 顯示出來。類庫中已經包含SwaggerUI 。所以不需要額外安裝。

2.快速開始

• 創建項目 OnlineAPI來封裝百度音樂服務(示例下載) ，通過API可以搜索、獲取音樂的信息和播放連接。

我盡量刪除一些我們demo中不會用到的一些文件，使其看上去比較簡潔。

• WebAPI 安裝 Swashbuckle

Install-Package Swashbuckle

• 代碼注釋生成文檔說明。
  Swashbuckle 是通過生成的XML文件來讀取注釋的，生成 SwaggerUI，JSON 配置中的說明的。
  安裝時會在項目目錄 App_Start 文件夾下生成一個 SwaggerConfig.cs 配置文件，用於配置 SwaggerUI 相關展示行為的。如圖：

• 將配置文件大概99行注釋去掉並修改為

c.IncludeXmlComments(GetXmlCommentsPath(thisAssembly.GetName().Name));

• 並在當前類中添加一個方法

/// <summary>
/// </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 文檔文件”，編譯過程中生成類庫的注釋文件

• 添加百度音樂 3個API

• 訪問 http://<youhost>/swagger/ui/index,最終顯示效果

• 我們通過API 測試API 是否成功運行

3.添加自定義HTTP Header

在開發移動端 API時常常需要驗證權限，驗證參數放在Http請求頭中是再好不過了。WebAPI配合過濾器驗證權限即可

首先我們需要創建一個 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"
                });
            }
        }
    }
}

在 SwaggerConfig.cs 的 EnableSwagger 配置匿名方法類添加一行注冊代碼

c.OperationFilter<HttpHeaderFilter>();

添加Web權限過濾器

using System;
using System.Collections.Generic;
using System.Linq;
using System.Net;
using System.Net.Http;
using System.Text;
using System.Web;
using System.Web.Http;
using System.Web.Http.Controllers;
using Newtonsoft.Json;

namespace OnlineAPI.Utility
{
    /// <summary>
    /// 
    /// </summary>
    public class AccessKeyAttribute : AuthorizeAttribute
    {
        /// <summary>
        /// 權限驗證
        /// </summary>
        /// <param name="actionContext"></param>
        /// <returns></returns>
        protected override bool IsAuthorized(HttpActionContext actionContext)
        {
            var request = actionContext.Request;
            if (request.Headers.Contains("access-key"))
            {
                var accessKey = request.Headers.GetValues("access-key").SingleOrDefault();
                //TODO 驗證Key
                return accessKey == "123456789";
            }
            return false;
        }

        /// <summary>
        ///     處理未授權的請求
        /// </summary>
        /// <param name="actionContext"></param>
        protected override void HandleUnauthorizedRequest(HttpActionContext actionContext)
        {
            var content = JsonConvert.SerializeObject(new {State = HttpStatusCode.Unauthorized});
            actionContext.Response = new HttpResponseMessage
            {
                Content = new StringContent(content, Encoding.UTF8, "application/json"),
                StatusCode = HttpStatusCode.Unauthorized
            };
        }
    }
}

在你想要的ApiController 或者是 Action 添加過濾器

[AccessKey]

最終顯示效果

4.顯示上傳文件參數

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"
                });
            }
        }
    }
}

在 SwaggerConfig.cs 的 EnableSwagger 配置匿名方法類添加一行注冊代碼

c.OperationFilter<UploadFilter>();

API 文檔展示效果

5.版本和資源

你可以通過下列連接獲取相關說明。
OnlineAPI Demo 項目下載
OnlineAPI Demo下載
Swashbuckle 項目地址：
https://github.com/domaindrivendev/Swashbuckle
swagger-ui 項目地址：
https://github.com/swagger-api/swagger-ui
swagger-ui 官網地址：
http://swagger.io/swagger-ui/