Asp.net Core WebApi 使用Swagger做協助文檔，並且自訂Swagger的UI

標籤：des   協助文檔   comm   應用   新版本   路徑   option   htm   源檔案   

WebApi寫好之後，線上協助文檔以及能夠線上調試的工具是專業化的表現，而Swagger毫無疑問是做Docs的最佳工具，自動產生每個Controller的介面說明，自動將參數解析成json，並且能夠線上調試。

那麼要講Swagger應用到Asp.net Core中需要哪些步驟，填多少坑呢？

安裝Swagger到項目

{    "dependencies": {                                "Swashbuckle": "6.0.0-beta902",                                ........

或者直接通過NuGet介面來添加Swashbuckle，目前最新版本6.0.0-beta902

配置Swagger

1.startup.cs=>configureServices

//文檔解析            services.AddSwaggerGen();//非必須            services.ConfigureSwaggerGen(options =>            {                options.SingleApiVersion(new Info                {                    Version = "v1",                    Title = "UFX.Mall商城對接企業內部系統服務中介軟體介面說明文檔"+Configuration.GetValue<string>("Customer"),                    Description = "Based on Asp.net Core WebApi，Powered By 柚凡資訊科技 www.cnunify.com"                });            });

2.startup.cs=>configure

//文檔解析            app.UseSwagger();            app.UseSwaggerUi();

3.自動讀取方法的描述資訊

參考文檔：https://docs.microsoft.com/en-us/aspnet/core/tutorials/web-api-help-pages-using-swagger

重點：如何自訂Swagger的UI

所有配置做完後，直接存取http://xxx/swagger/ui 即可看到介面的介面了

但是預設的swagger UI個人認為還是有點醜陋，部分細節處理不到位，swagger的所有資源檔都是嵌入型的，無法直接修改，雖然提供部分ui介面，但如何才能完全自訂UI呢？

swagger是前後端完全分離的項目，前端靜態檔案通過ajax，請求json資料，返回介面的解析顯示到頁面上，swagger-ui可以在git中找到：https://github.com/swagger-api/swagger-ui/

將swagger-ui下載到本地，然後將dist裡的所有檔案放在wwwroot->swagger->ui

然後配置讓asp.net core自動讀取wwwroot的真實路徑。

// This method gets called by the runtime. Use this method to configure the HTTP request pipeline        public void Configure(IApplicationBuilder app, IHostingEnvironment env, ILoggerFactory loggerFactory)        {            loggerFactory.AddConsole(Configuration.GetSection("Logging"));            loggerFactory.AddDebug();            //配置NLog            loggerFactory.AddNLog();            env.ConfigureNLog("nlog.config");            app.UseApplicationInsightsRequestTelemetry();            app.UseApplicationInsightsExceptionTelemetry();            //異常處理中介軟體            app.UseMiddleware(typeof(ExceptionHandlerMiddleWare));            app.UseMvc();            // Enable static files middleware.            app.UseStaticFiles();            app.UseMvcWithDefaultRoute();            //文檔解析            app.UseSwagger();            app.UseSwaggerUi();        }

這樣，所有swagger檔案都在本地了，想怎樣自訂都可以，show一下修改過的UI

當webapi發布到伺服器，訪問的時候右下角swagger會有一個異常錯誤，要取消該錯誤，只需要將index.html裡加入validatorUrl設定為null，取消對url的驗證即可

            window.swaggerUi = new SwaggerUi({                url: url,                validatorUrl: null,                dom_id: "swagger-ui-container",

參考文檔：http://stackoverflow.com/questions/27808804/swagger-ui-shows-error-validation-when-deployed

同時swagger還提供一個介面文檔編輯器swagger-editor，可以方便的編輯swagger.json，編輯好了可以匯出到工程中

http://editor.swagger.io/

Asp.net Core WebApi 使用Swagger做協助文檔，並且自訂Swagger的UI