net core Webapi基礎工程搭建（三）——在線接口文檔Swagger

目錄

• 前言
• Swagger
• NuGet引用第三方類庫
• 別急，還有
• 沒錯，註釋
• 小結

前言

先後分離的好處，就是後端埋頭作業務邏輯功能，不須要過多考慮用戶體驗，只專一於數據、性能開發，對於前端須要的數據能夠經過組Json或者其餘方式回調，可是先後兩端須要肯定好接口Api的規範，而且前端若是須要查看接口的相關信息，就須要文檔的支撐了。那麼問題來了，後端在開發過程當中每次改動接口，都須要改動文檔，累不累。

Swagger

Swagger做爲一個在線文檔，經過後端的接口控制器生成一套Json串數據，實時展現後端的接口請求地址，參數，類型以及回調，很好的解決這個問題（後端能夠給前端一個Swagger的地址，而後來句你本身看吧，固然仍是須要多溝通的），這個在Java裏用過以後，就立刻看看有沒有.net的版本，果真，語言都是相通的，廢話很少說，開始第三方類庫的引用。

NuGet引用第三方類庫

工具->NuGet包管理器->管理解決方案的NuGet程序包...
在瀏覽中查找"Swashbuckle.AspNetCore"，選擇項目工程，點擊安裝。

引入完成後，在Startup.cs文件ConfigureServices中，加入如下代碼：

public void ConfigureServices(IServiceCollection services)
        {
            services.AddMvc().SetCompatibilityVersion(CompatibilityVersion.Version_2_2);
            
           #region Swagger
            services.AddSwaggerGen(options =>
            {
                options.SwaggerDoc("v1", new Info
                {
                    Version = "v1.1.0",
                    Title = "April WebAPI",
                    Description = "後臺框架",
                    TermsOfService = "None",
                    Contact = new Contact { Name = "Blank", Email = "1829027193@qq.com", Url = "http://www.aprilblank.com" }
                });
            });
            #endregion 
        }

在Startup.cs類裏編輯Configure方法，加入如下代碼：

public void Configure(IApplicationBuilder app, IHostingEnvironment env)
        {
           …
           
            #region Swagger
            app.UseSwagger();
            app.UseSwaggerUI(options =>
            {
                options.SwaggerEndpoint("/swagger/v1/swagger.json", "ApiHelp V1");
            });
            #endregion

            app.UseHttpsRedirection();
            app.UseMvc();
        }

從新生成工程後，訪問你的端口/swagger就能夠看到接口文檔幫助界面了。

別急，還有

在線的接口文檔是有了，可一個接口啥意思都不知道，前端仍是得一臉懵逼問你，這個接口啥意思啊，這個參數啥意思啊什麼的。

沒錯，註釋

仍是在Startup.cs文件ConfigureServices中，加入如下代碼：

public void ConfigureServices(IServiceCollection services)
        {
            services.AddMvc().SetCompatibilityVersion(CompatibilityVersion.Version_2_2);
            #region Swagger
            services.AddSwaggerGen(options =>
            {
                options.SwaggerDoc("v1", new Info
                {
                    Version = "v1.1.0",
                    Title = "April WebAPI",
                    Description = "後臺框架",
                    TermsOfService = "None",
                    Contact = new Contact { Name = "Blank", Email = "790048789@qq.com", Url = "http://www.aprilblank.com" }
                });
                
                // 爲 Swagger JSON and UI設置xml文檔註釋路徑
                var basePath = Path.GetDirectoryName(AppContext.BaseDirectory);//獲取應用程序所在目錄（絕對，不受工做目錄影響，建議採用此方法獲取路徑）
                var xmlPath = Path.Combine(basePath, "April.xml");
                options.IncludeXmlComments(xmlPath);
                
            });
            #endregion
        }

右鍵WebApi這個項目工程，點擊屬性，在生成這一欄

先拿Values這個控制器作實驗

從新生成後會在對應目錄看到有Apirl.xml文檔文件，運行以後查看/Swagger

點開剛纔單獨註釋參數的/api/Values/{id}

小結

一個WebApi工程離不開文檔，而一個在線文檔能夠省掉本身不少事，而且Swagger也支持在線調試，雖然說我本身仍是傾向於Postman（後續會介紹相關工具），這個在線文檔不只是方便了前端查看，總之在開發上確實是一個利器。

下一篇，介紹後臺核心之一，Log日誌。