【WEB API項目實戰干貨系列】- 接口文檔與在線測試(二)

上一篇: 【WEB API項目實戰干貨系列】- Web API 2入門(一)

這一篇我們主要介紹如何做API幫助文檔，給API的調用人員介紹各個 API的功能, 輸入參數，輸出參數, 以及在線測試 API功能(這個也是方便我們自己開發調試)

我們先來看看我們的API最終幫助文檔及在線測試最終達到的效果:

概要圖

 

GET API

添加產品API:

刪除產品 API

接下來我們動手來實現上面的功能

給所有API添加注釋信息

代碼如下

[RoutePrefix("api/products")]
    public class ProductController : ApiController
    {
        /// <summary>
        /// 產品分頁數據獲取
        /// </summary>
        /// <returns></returns>
        [HttpGet, Route("product/getList")]
        public Page<Product> GetProductList()
        {
            throw new NotImplementedException();
        }

        /// <summary>
        /// 獲取單個產品
        /// </summary>
        /// <param name="productId"></param>
        /// <returns></returns>
        [HttpGet, Route("product/get")]
        public Product GetProduct(Guid productId)
        {
            throw new NotImplementedException();
        }

        /// <summary>
        /// 添加產品
        /// </summary>
        /// <param name="product"></param>
        /// <returns></returns>
        [HttpPost, Route("product/add")]
        public Guid AddProduct(Product product)
        {
            throw new NotImplementedException();
        }

        /// <summary>
        /// 更新產品
        /// </summary>
        /// <param name="productId"></param>
        /// <param name="product"></param>
        [HttpPost, Route("product/update")]
        public void UpdateProduct(Guid productId, Product product)
        {
            throw new NotImplementedException();
        }

        /// <summary>
        /// 刪除產品
        /// </summary>
        /// <param name="productId"></param>
        [HttpDelete, Route("product/delete")]
        public void DeleteProduct(Guid productId)
        {
            throw new NotImplementedException();
        }
    }

我們上圖中顯示的api幫助信息，全部從我們的注釋信息中提取，所以這里的API注釋信息必不可少.

 

添加Swagger.Net組件(自定義修改版本, 官方已多年不更新，只能自己更新了)

在項目中加入Swagger.Net組件, 由於這個已經在官方的版本上做了很多的更新，大家實踐的過程中，直接從項目代碼中復制(必要的時候可以做成Nuget組件發布后大家使用)

添加Swagger.NET步驟:

1. 在項目中引入Swagger.Net Project.

2. 在Web API項目的App_Start下面添加SwaggerNet.cs

代碼如下

[assembly: WebActivatorEx.PreApplicationStartMethod(typeof(SwaggerNet), "PreStart")]
[assembly: WebActivatorEx.PostApplicationStartMethod(typeof(SwaggerNet), "PostStart")]
namespace Niusys.WebAPI.App_Start
{
    public static class SwaggerNet
    {
        public static void PreStart()
        {
            RouteTable.Routes.MapHttpRoute(
                name: "SwaggerApi",
                routeTemplate: "api/docs/{controller}/{action}",
                defaults: new { swagger = true }
            );
        }

        public static void PostStart()
        {
            var config = GlobalConfiguration.Configuration;
            config.Filters.Add(new SwaggerActionFilter());
        }
    }
}

其主要是注冊api文檔的請求路由及攔截文檔的請求.

3. 復制WebAPI項目中的SwaggerUI文件夾, 這里是幫助文檔的頁面處理文件.

4. WebAPI項目啟用XML文檔生成

 

這個時候就可以啟動項目，在URL中輸入swaggerui（http://localhost:14527/swaggerui/）目錄，就可以訪問我們的API幫助文檔系統及在線測試了。

 

總結:

這里幫助文檔的原理是通過我們在代碼中的XML注釋來實現的，其原理也是在請求到api/doc的時候，這個時候去取對應controler/action的xml幫助文檔，讓后做顯示.

其測試是完全用的其內部瘋轉的jQuery Ajax來做的測試, 跟界面做了高度集成, 完全滿足我們項目的需求。

 

本篇代碼: 代碼下載(代碼托管在CSDN Code)