.NET Framework4.7.2 製作 Web API 使用 [NSwag] 套件呈現 Swagger UI + JWT Authentication 及跨域處理(CORS)

link之家

链接快照平台

输入网页链接，自动生成快照
标签化管理网页链接

相关文章推荐

大力的跑步机 · springbboot整合springdoc ...· 1 周前 ·

有情有义的铁板烧 · 《温州一家人》_中国作家网· 3 周前 ·

没有腹肌的八宝粥 · 招聘信息 | ...· 5 月前 ·

才高八斗的地瓜 · 【动漫推荐/迷番】欢迎来到！水龙。敬-大乐园 ...· 10 月前 ·

胡子拉碴的松球 · 【全国5年以下3-5万二手福田】全国5年以下 ...· 1 年前 ·

咆哮的梨子 · 跨年夜情侣怎么拍_跨年夜情侣怎么拍照好看_跨 ...· 1 年前 ·

.NET Framework4.7.2 製作 Web API 使用 [NSwag] 套件呈現 Swagger UI + JWT Authentication 及跨域處理(CORS) swagger web api public class JwtAuthUtil private readonly ApplicationDbContext db = new ApplicationDbContext(); // DB 連線 /// <summary> /// 生成 JwtToken /// </summary> /// <param name="id">會員id</param> /// <returns>JwtToken</returns> public string GenerateToken(int id) // 自訂字串，驗證用，用來加密送出的 key (放在 Web.config 的 appSettings) string secretKey = WebConfigurationManager.AppSettings["TokenKey"]; // 從 appSettings 取出 var user = db.User.Find(id); // 進 DB 取出想要夾帶的基本資料 // payload 需透過 token 傳遞的資料 (可夾帶常用且不重要的資料) var payload = new Dictionary<string, object> { "Id", user.Id }, { "Account", user.Account }, { "NickName", user.NickName }, { "Image", user.Image }, { "Exp", DateTime.Now.AddMinutes(30).ToString() } // JwtToken 時效設定 30 分 // 產生 JwtToken var token = JWT.Encode(payload, Encoding.UTF8.GetBytes(secretKey), JwsAlgorithm.HS512); return token; /// <summary> /// 生成只刷新效期的 JwtToken /// </summary> /// <returns>JwtToken</returns> public string ExpRefreshToken(Dictionary<string, object> tokenData) string secretKey = WebConfigurationManager.AppSettings["TokenKey"]; // payload 從原本 token 傳遞的資料沿用，並刷新效期 var payload = new Dictionary<string, object> { "Id", (int)tokenData["Id"] }, { "Account", tokenData["Account"].ToString() }, { "NickName", tokenData["NickName"].ToString() }, { "Image", tokenData["Image"].ToString() }, { "Exp", DateTime.Now.AddMinutes(30).ToString() } // JwtToken 時效刷新設定 30 分 //產生刷新時效的 JwtToken var token = JWT.Encode(payload, Encoding.UTF8.GetBytes(secretKey), JwsAlgorithm.HS512); return token; /// <summary> /// 生成無效 JwtToken /// </summary> /// <returns>JwtToken</returns> public string RevokeToken() string secretKey = "RevokeToken"; // 故意用不同的 key 生成 var payload = new Dictionary<string, object> { "Id", 0 }, { "Account", "None" }, { "NickName", "None" }, { "Image", "None" }, { "Exp", DateTime.Now.AddDays(-15).ToString() } // 使 JwtToken 過期失效 // 產生失效的 JwtToken var token = JWT.Encode(payload, Encoding.UTF8.GetBytes(secretKey), JwsAlgorithm.HS512); return token;

在登入功能的 API 確認登入成功後，生成 JwtToken 並回傳給前端

// GenerateToken() 生成新 JwtToken 用法
JwtAuthUtil jwtAuthUtil = new JwtAuthUtil();
string jwtToken = jwtAuthUtil.GenerateToken(userQuery.Id); 
// 登入成功時，回傳登入成功順便夾帶 JwtToken
return Ok(new { Status = true, JwtToken = jwtToken });
前端將收到的 JWT-Token 字串存入瀏覽器 localStorage
建立一個類別 JwtAuthFilter.cs，負責生成 [JwtAuthFilter] 標籤，可放於需登入的 API 上，用來檢核 JWT-Token 是否正確
using Jose;
using Newtonsoft.Json;
using System;
using System.Collections.Generic;
using System.Net.Http;
using System.Text;
using System.Web.Configuration;
using System.Web.Http;
using System.Web.Http.Controllers;
using System.Web.Http.Filters;
namespace MyWebApiProject.Security
    /// <summary>
    /// JwtAuthFilter 繼承 ActionFilterAttribute 可生成 [JwtAuthFilter] 使用
    /// </summary>
    public class JwtAuthFilter : ActionFilterAttribute
        // 加解密的 key，如果不一樣會無法成功解密
        private static readonly string secretKey = WebConfigurationManager.AppSettings["TokenKey"];
        /// <summary>
        /// 過濾有用標籤 [JwtAuthFilter] 請求的 API 的 JwtToken 狀態及內容
        /// </summary>
        /// <param name="actionContext"></param>
        public override void OnActionExecuting(HttpActionContext actionContext)
            // 取出請求內容並排除不需要驗證的 API
            var request = actionContext.Request;
            if (!WithoutVerifyToken(request.RequestUri.ToString())) {
                // 有取到 JwtToken 後，判斷授權格式不存在且不正確時
                if (request.Headers.Authorization == null || request.Headers.Authorization.Scheme != "Bearer") {
                    // 可考慮配合前端專案開發期限，不修改 StatusCode 預設 200，將請求失敗搭配 Status: false 供前端判斷
                    string messageJson = JsonConvert.SerializeObject(new { Status = false, Message = "請重新登入" }); // JwtToken 遺失，需導引重新登入
                    var errorMessage = new HttpResponseMessage()
                        // StatusCode = System.Net.HttpStatusCode.Unauthorized, // 401
                        ReasonPhrase = "JwtToken Lost",
                        Content = new StringContent(messageJson,
                                    Encoding.UTF8,
                                    "application/json")
                    throw new HttpResponseException(errorMessage); // Debug 模式會停在此行，點繼續執行即可
                else {
                    try {
                        // 有 JwtToken 且授權格式正確時執行，用 try 包住，因為如果有篡改可能解密失敗
                        // 解密後會回傳 Json 格式的物件 (即加密前的資料)
                        var jwtObject = GetToken(request.Headers.Authorization.Parameter);
                        // 檢查有效期限是否過期，如 JwtToken 過期，需導引重新登入
                        if (IsTokenExpired(jwtObject["Exp"].ToString())) {
                            string messageJson = JsonConvert.SerializeObject(new { Status = false, Message = "請重新登入" }); // JwtToken 過期，需導引重新登入
                            var errorMessage = new HttpResponseMessage()
                                // StatusCode = System.Net.HttpStatusCode.Unauthorized, // 401
                                ReasonPhrase = "JwtToken Expired",
                                Content = new StringContent(messageJson,
                                    Encoding.UTF8,
                                    "application/json")
                            throw new HttpResponseException(errorMessage); // Debug 模式會停在此行，點繼續執行即可
                    catch (Exception) {
                        // 解密失敗
                        string messageJson = JsonConvert.SerializeObject(new { Status = false, Message = "請重新登入" }); // JwtToken 不符，需導引重新登入
                        var errorMessage = new HttpResponseMessage()
                            // StatusCode = System.Net.HttpStatusCode.Unauthorized, // 401
                            ReasonPhrase = "JwtToken NotMatch",
                            Content = new StringContent(messageJson,
                                    Encoding.UTF8,
                                    "application/json")
                        throw new HttpResponseException(errorMessage); // Debug 模式會停在此行，點繼續執行即可
            base.OnActionExecuting(actionContext);
        /// <summary>
        /// 將 Token 解密取得夾帶的資料
        /// </summary>
        /// <param name="token"></param>
        /// <returns></returns>
        public static Dictionary<string, object> GetToken(string token)
            return JWT.Decode<Dictionary<string, object>>(token, Encoding.UTF8.GetBytes(secretKey), JwsAlgorithm.HS512);
        /// <summary>
        /// 有在 Global 設定一律檢查 JwtToken 時才需設定排除，例如 Login 不需要驗證因為還沒有 token
        /// </summary>
        /// <param name="requestUri"></param>
        /// <returns></returns>
        public bool WithoutVerifyToken(string requestUri)
            //if (requestUri.EndsWith("/login")) return true;
            return false;
        /// <summary>
        /// 驗證 token 時效
        /// </summary>
        /// <param name="dateTime"></param>
        /// <returns></returns>
        public bool IsTokenExpired(string dateTime)
            return Convert.ToDateTime(dateTime) < DateTime.Now;
使用者用到需登入的 API 時，前端取出瀏覽器 localStorage 中的 JWT-Token 字串用於請求的 Header 裡 Authorization 欄位用 Bearer 規則夾帶
將 [JwtAuthFilter] 標籤，放於需登入的 API 上，檢核 JWT-Token 是否正確，並刷新效期
// 取出請求內容，解密 JwtToken 取出資料
var userToken = JwtAuthFilter.GetToken(Request.Headers.Authorization.Parameter);
// ExpRefreshToken() 生成刷新效期 JwtToken 用法
JwtAuthUtil jwtAuthUtil = new JwtAuthUtil();
string jwtToken = jwtAuthUtil.ExpRefreshToken(userToken);
// Do Something ~
// 處理完請求內容後，順便送出刷新效期的 JwtToken
return Ok(new { Status = true, JwtToken = jwtToken });
用於強制登出使用者的方式
// RevokeToken() 生成失效的 JwtToken 用法
JwtAuthUtil jwtAuthUtil = new JwtAuthUtil();
string jwtToken = jwtAuthUtil.RevokeToken();
// 用於登出使用者時，刷新為失效的 JwtToken
return Ok(new { Status = true, jwtToken = jwtToken });
Web API 使用 [NSwag] 套件呈現 Swagger UI
ASP.NET WebAPI 2 整合 NSwag (@後端實作主要參考)
如何在 ASP․NET Core 3 完整設定 NSwag 與 OpenAPI v3 文件
ASP.NET WebAPI 2 + NSwag - 實作簡單 ApiKey Header + IP 權限管控
NuGet 安裝套件
NSwag.AspNet.Owin  version="13.15.9"
NSwag.Annotations version="13.2.5"
Microsoft.AspNet.WebApi.Owin version="5.2.7"
Microsoft.Owin.Host.SystemWeb version="4.2.0"
程式碼實作
在專案新增 OWIN 啟動類別 Startup.cs，並加入相關設定
using Microsoft.Owin;
using NSwag;
using NSwag.AspNet.Owin;
using NSwag.Generation.Processors.Security;
using Owin;
using System.Web.Http;
[assembly: OwinStartup(typeof(MyWebApiProject.Startup))]
namespace MyWebApiProject
    /// <summary>
    /// OWIN 啟動類別
    /// </summary>
    public class Startup
        /// <summary>
        /// 應用程式配置
        /// </summary>
        /// <param name="app"></param>
        public void Configuration(IAppBuilder app)
            // 如需如何設定應用程式的詳細資訊，請瀏覽 https://go.microsoft.com/fwlink/?LinkID=316888
            var config = new HttpConfiguration();
            // 針對 JSON 資料使用 camel (JSON 回應會改 camel，但 Swagger 提示不會)
            //config.Formatters.JsonFormatter.SerializerSettings.ContractResolver = new CamelCasePropertyNamesContractResolver();
            app.UseSwaggerUi3(typeof(Startup).Assembly, settings =>
                // 針對 WebAPI，指定路由包含 Action 名稱
                settings.GeneratorSettings.DefaultUrlTemplate =
                    "api/{controller}/{action}/{id?}";
                // 加入客製化調整邏輯名稱版本等
                settings.PostProcess = document =>
                    document.Info.Title = "WebAPI : 專案名稱";
                // 加入 Authorization JWT token 定義
                settings.GeneratorSettings.DocumentProcessors.Add(new SecurityDefinitionAppender("Bearer", new OpenApiSecurityScheme()
                    Type = OpenApiSecuritySchemeType.ApiKey,
                    Name = "Authorization",
                    Description = "Type into the textbox: Bearer {your JWT token}.",
                    In = OpenApiSecurityApiKeyLocation.Header,
                    Scheme = "Bearer" // 不填寫會影響 Filter 判斷錯誤
                // REF: https://github.com/RicoSuter/NSwag/issues/1304 (每支 API 單獨呈現認證 UI 圖示)
                settings.GeneratorSettings.OperationProcessors.Add(new OperationSecurityScopeProcessor("Bearer"));
            app.UseWebApi(config);
            config.MapHttpAttributeRoutes();
            config.EnsureInitialized();
於專案屬性的建置內容勾選輸出 XML 文件檔案， Swagger UI 才會有方法及參數說明
於 Web.config 加入處理器設定，將 URL /swagger/* 導向 NSwag 處理程式
<configuration>
	<system.webServer>
		<handlers>
			<add name="NSwag" path="swagger" verb="*" type="System.Web.Handlers.TransferRequestHandler" preCondition="integratedMode,runtimeVersionv4.0" />
		</handlers>
	</system.webServer>
</configuration>
於 API 及輸入欄位加上 /// 撰寫 XML 方法及參數說明
使用登入 API 取得回傳的 JWT token 於 Swagger UI 的 Authorization JWT token 輸入驗證時，使用 Bearer + 空格 + JWT token 夾帶
可於 ApiController 上加入 [OpenApiTag] 描述整個模組功能
[OpenApiTag("Users", Description = "使用者操作功能")]
public class UsersController : ApiController
 	/// <summary>
    /// 1-5 聯絡我們功能 (JWT)
    /// </summary>
    /// <param name="contactUsVm">留言資料</param>
    /// <returns></returns>
 	/// <summary>
    [JwtAuthFilter] // 用於檢核 JWT-Token 
    [HttpPost]
    [SwaggerResponse(typeof(ApiResult))] // 顯示回傳資料的註解
    [Route("api/users/contact-us")]
    public IHttpActionResult SendContactUsMail(ContactUsVm contactUsVm)
        // Do Sometning
        // 取出請求內容，解密 JwtToken 取出資料
        var userToken = JwtAuthFilter.GetToken(Request.Headers.Authorization.Parameter);
        //單純刷新效期不新生成，新生成會進資料庫
        JwtAuthUtil jwtAuthUtil = new JwtAuthUtil();
        string jwtToken = jwtAuthUtil.ExpRefreshToken(userToken);
        // 送出刷新 JwtToken
        return Ok(new ApiResult { Status = true, JwtToken = jwtToken });
            var config = new HttpConfiguration();
            // 針對 JSON 資料使用 camel (JSON 回應會改 camel，但 Swagger 提示不會)
            //config.Formatters.JsonFormatter.SerializerSettings.ContractResolver = new CamelCasePropertyNamesContractResolver();
            app.UseSwaggerUi3(typeof(Startup).Assembly, settings =>
                // 針對 WebAPI，指定路由包含 Action 名稱
                settings.GeneratorSettings.DefaultUrlTemplate =
                    "api/{controller}/{action}/{id?}";
                // 加入客製化調整邏輯名稱版本等
                settings.PostProcess = document =>
                    document.Info.Title = "WebAPI : 專案名稱";
                // 加入 Authorization JWT token 定義
                settings.GeneratorSettings.DocumentProcessors.Add(new SecurityDefinitionAppender("Bearer", new OpenApiSecurityScheme()
                    Type = OpenApiSecuritySchemeType.ApiKey,
                    Name = "Authorization",
                    Description = "Type into the textbox: Bearer {your JWT token}.",
                    In = OpenApiSecurityApiKeyLocation.Header,
                    Scheme = "Bearer" // 不填寫會影響 Filter 判斷錯誤
                // REF: https://github.com/RicoSuter/NSwag/issues/1304 (每支 API 單獨呈現認證 UI 圖示)
                settings.GeneratorSettings.OperationProcessors.Add(new OperationSecurityScopeProcessor("Bearer"));
            app.UseWebApi(config);
            config.MapHttpAttributeRoutes();
            config.EnsureInitialized();
        /// <summary>
        /// 啟用跨域及驗證配置
        /// </summary>
        /// <param name="app"></param>
        private void ConfigureAuth(IAppBuilder app)
            // 建立 OAuth 配置
            var oAuthOptions = new OAuthAuthorizationServerOptions
                Provider = new AuthorizationServerProvider()
            // 啟用 OAuth2 bearer tokens 驗證並加入配置
            app.UseOAuthAuthorizationServer(oAuthOptions);
新增 AuthorizationServerProvider.cs 類別檔，設定跨域 Request Headers 處理邏輯
using Microsoft.Owin;
using Microsoft.Owin.Security.OAuth;
using System;
using System.Configuration;
using System.Linq;
using System.Threading.Tasks;
namespace MyWebApiProject.Security
    /// <summary>
    /// OAuth 配置並繼承 OAuthAuthorizationServerProvider
    /// </summary>
    public class AuthorizationServerProvider : OAuthAuthorizationServerProvider
        /// <summary>
        /// 在驗證客戶端身分前調用，並依客戶端請求來源配置 CORS 允許類型設定
        /// </summary>
        /// <param name="context"></param>
        /// <returns></returns>
        public override Task MatchEndpoint(OAuthMatchEndpointContext context)
            // 依請求來源配置 CORS 允許類型設定
            SetCORSPolicy(context.OwinContext);
            // 如果請求為預檢請求則設為完成直接回傳
            if (context.Request.Method == "OPTIONS") {
                context.RequestCompleted();
                return Task.FromResult(0);
            return base.MatchEndpoint(context);
        /// <summary>
        /// 依請求來源配置 CORS 允許類型設定
        /// </summary>
        /// <param name="context"></param>
        private void SetCORSPolicy(IOwinContext context)
            // 取出允許跨域的網址 (放在 Web.config 的 appSettings)
            string allowedUrls = ConfigurationManager.AppSettings["allowedOrigins"];
            // 有填寫允許跨域的網址，就分割取出判斷請求的來源是否等於允許跨域的網址，並將允許網址加入 Headers
            if (!String.IsNullOrWhiteSpace(allowedUrls)) {
                var list = allowedUrls.Split(',');
                if (list.Length > 0) {
                    string origin = context.Request.Headers.Get("Origin");
                    var found = list.Where(item => item == origin).Any();
                    if (found) {
                        context.Response.Headers.Add("Access-Control-Allow-Origin",
                                                     new string[] { origin });
            // 配置允許請求的 Headers 內容
            context.Response.Headers.Add("Access-Control-Allow-Headers",
                                   new string[] { "Authorization", "Content-Type" });
            // 配置允許請求的 Headers 方法
            context.Response.Headers.Add("Access-Control-Allow-Methods",
                                   new string[] { "OPTIONS", "GET", "POST", "PUT", "DELETE"});
於 Web.config 加入允許前端跨域請求的網址 (若無需求可不填)
可填測試網域或前端開發時使用的本地端網域，用逗點區隔添加
<configuration>
  <appSettings>
	  <!--Owin CORS-->
	  <add key="allowedOrigins" value="https://www.myfriendproject.com,https://localhost:44444,http://127.0.0.1:5500" />
  </appSettings>
</configuration>
複雜型別 ⇒ 會自動轉到 Body ⇒ 所以如果要當 GET 用並夾在 uri ⇒ API輸入資料型別前才要加 [FromUri] ⇒ Swagger UI 會變成每個值都是個別輸入欄位
簡單型別 ⇒ 會自動轉到 Uri ⇒ 所以如果要當 POST 用並藏到 body ⇒ API輸入資料型別前才要加 [FromBody] ⇒ Swagger UI 會變成一個可以輸入多行的欄位
[OpenApiTag("Users", Description = "使用者操作功能")]
public class UsersController : ApiController
    /// <summary>
    /// 1-5 聯絡我們功能 (JWT)
    /// </summary>
    /// <param name="contactUsVm">留言資料</param>
    /// <returns></returns>
    /// <summary>
    [JwtAuthFilter] // 用於檢核 JWT-Token 
    [HttpPost]
    [SwaggerResponse(typeof(ApiResult))] // 顯示回傳資料的註解
    [Route("api/users/contact-us")]
    public IHttpActionResult SendContactUsMail([FromUri] ContactUsVm contactUsVm)
        // Do Sometning