① 如何使 WebAPI 自動生成漂亮又實用在線API文檔
1.1 SwaggerUI
SwaggerUI 是一個簡單的Restful API 測試和文檔工具。簡單、漂亮、易用（官方）。通過讀取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 文檔展示效果
② MVC2，MVC3，MVC4和MVC5的不同
MVC2，MVC3，MVC4和MVC5的不同：
1、查看引擎:
視圖引擎負責將HTML代碼從視圖呈現到瀏覽器。
MVC 2僅使用Web窗體視圖引擎( .aspx)作為默認視圖引擎。
MVC3使用剃刀視圖引擎( .c#和的cshtml。vbhtml (用於Visual Basic )和Web窗體視圖引擎( .阿斯佩克斯)。
MVC4還使用剃刀視圖引擎作為默認視圖引擎，具有一些新功能，如條件屬性和「波形斜線」。
2、圖表、網路網格、加密、網路映像、網路郵件控制:
所有這些在MVC2中都不可用。
所有這些都在MVC3和MVC4中提供。
3、合成語法：
Web窗體視圖引擎語法: < % = HTML代碼%>在MVC2中。
(剃刀語法)剃刀視圖引擎語法: @MVC3中的Html代碼。
MVC4具有相同的剃刀視圖引擎語法，但添加了新功能，如條件屬性和「波形斜線」，即URL解析。
4、可用於在視圖和控制器之間共享數據的對象:
模板數據、視圖數據在MVC2中可用。
MVC3中提供了臨時數據、視圖數據、視圖包。
MVC4中提供了臨時數據、視圖數據、視圖包。
>TempData用於當前和後續請求，即當您知道要重定向的下一個視圖時。
>在ViewData中，可以通過字元串作為鍵訪問對象字典。
>在c#4.0中添加了ViewBag，它使用允許動態添加對象屬性的動態功能。我們可以說ViewBag = ViewData +ViewData字典周圍的動態特性。
5、jquery支持:
jquery支持在MVC2中很好。
在MVC3中，jquery支持更好。
MVC4為Jquery (如Jquery Mobile)提供了更好的支持。
6、驗證:
MVC2中有客戶端驗證和非同步控制器。
MVC3中包含不引人注目的Ajax和客戶端驗證、Jquery驗證和JSON綁定支持。
客戶端驗證、Jquery驗證和對MVC4非同步方法的增強支持。
7、項目模板:
MVC3支持由HTML5啟用的項目模板。
MVC4支持移動應用程序的許多新功能，還提供了新的移動項目模板和更新和現代化的默認模板。
8、ASP.NET MVC 5中的新功能:
（1）一個ASP網；
（2）ASP凈身份；
（3）MVC模板中的引導程序；
（4）認證過濾器；
（5）過濾器覆蓋。
③ c#webapi介面怎麼加上安全校驗
下面這幾個注意事項或許可以幫你一些
1. 找到Web應用所有的輸入點，找到所有的能接受用戶輸入的地方，漏掉輸入點也就漏掉了可能存在的縫。
2. 過濾每一個輸入點，為每個輸入點設定相應的校驗規則和邊界。
3. 不要忘記校驗哪些隱藏域，cookie和url參數。
4. 驗證從資料庫裡面得到的數據，這個是最容易忽視的地方，不要相信來自資料庫裡面的數據就是合法的數據。
5. 你是如何做輸入校驗的？ javascript？如果只是用javascript做客戶端校驗, 風險還是很大的，一定要確保加上服務端的校驗，否則如果客戶端禁用了javascript或者客戶端代碼被人工修改，非法數據還是會進入系統內部的。
6. 隱藏異常信息，再周全的校驗也不可能覆蓋所有的case，如果非法數據造成了系統的異常，不要將詳細的異常信息暴露給客戶端，這些異常信息有可能成為系統的攻擊入口。
在做輸入校驗的時候，從「什麼樣的輸入才是合法的」入手會降低驗證失效的風險，應該只為每個輸入點的輸入內容制定一個有限的，剛好夠用的合法范圍，除此之外的所有內容都當做是非法的。而從「什麼樣的輸入是不合法的」入手則會增加驗證失效的可能，因為你不可能窮舉非法的輸入。