前言

    目前市場上主流的開發模式，幾乎清一色的前後端分離方式，作為服務端開發人員，我們有義務提供給各個客戶端良好的開發文件，以方便對接，減少溝通時間，提高開發效率；對於開發人員來說，編寫介面文件需要消耗大量的時間，並且，手動編寫的文件介面會由於需求的頻繁變動變得難以維護，這就需要一個在介面開發階段可以自動監測介面輸入引數，自動生成文件的功能；由於 Swagger 外掛的出現，這項工作幾乎可以實現完全的自動化。

1. 什麼是 Swagger

    Swagger 是由 SmartBear 公司開發的一款 API 文件自動化工具，其採用 Apache 2.0 免費開源授權協議，允許任何人免費使用該工具，利用 Swagger 的特性，可以很方便在沒有任何實現邏輯的情況下生成視覺化和與API資源互動介面，Swagger 支援 API 分類導航，提供 API 測試套件，完全的可定製化，對開發人員和 API 消費者都非常友好。

2. 開始使用 Swagger

• 2.1 首先建立一個 Asp.Net Core API 專案，並從 NuGet 上引用 Swagger 包

• 2.2 右鍵點選專案“依賴項”，選擇 “管理 NuGet 程式包(N)”，這瀏覽標籤頁輸入包名進行安裝，選擇穩定版即可，此處我選擇的版本是 4.0.1

Swashbuckle.AspNetCore
Swashbuckle.AspNetCore.Annotations

• 2.3 首先我們要對專案進行設定，確保生成專案的 XML 文件，如下圖
  右鍵點選專案-屬性-生成，勾選 "XML 文件檔案"

• 2.4 接下來需要在 Startup.cs 中將 Swagger 加入管道中

        static string[] docs = new[] { "未分類" };

        public void ConfigureServices(IServiceCollection services)
        {
            services.AddMvc().SetCompatibilityVersion(CompatibilityVersion.Version_2_1);

            if (Env.IsDevelopment())
            {
                services.AddSwaggerGen(options =>
               {
                   foreach (var doc in docs) options.SwaggerDoc(doc, new Info { Version = doc });
                   options.DocInclusionPredicate((docName, description) =>
                   {
                       description.TryGetMethodInfo(out MethodInfo mi);

                       var attr = mi.DeclaringType.GetCustomAttribute<ApiExplorerSettingsAttribute>();
                       if (attr != null)
                       {
                           return attr.GroupName == docName;
                       }
                       else
                       {
                           return docName == "未分類";
                       }
                   });
                   options.CustomSchemaIds(d => d.FullName);
                   options.IncludeXmlComments("Ron.SwaggerTest.xml", true);
               });
            }
        }

        // This method gets called by the runtime. Use this method to configure the HTTP request pipeline.
        public void Configure(IApplicationBuilder app, IHostingEnvironment env)
        {
            if (env.IsDevelopment())
            {
                app.UseDeveloperExceptionPage();
                app.UseSwagger()
                   .UseSwaggerUI(options =>
                {
                    options.DocumentTitle = "Ron.liang Swagger 測試文件";
                    foreach (var item in docs)
                        options.SwaggerEndpoint($"/swagger/{item}/swagger.json", item);
                });
            }

            app.UseMvc();
        }
    }
 

• 2.5 以上程式碼首先定義了一個常量，表示文件分類列表，預設值給了一個 “未分類”，然後在 ConfigureServices 和 Configure 方法中判斷是開發環境才會引用 Swagger 進行 API 文件的生成，之所以要增加一個 “未分類”，是因為在我們沒有對 API 進行分組的時候，預設把未分組的 API 歸併到此分類下，好了，現在執行專案

• 2.6 這瀏覽器中輸入地址

http://localhost:5000/swagger/index.html

• 看到 API 文件已經成功生成

• 可以看到，各種不同的 HttpMethod 都有不同的顏色進行區分顯示，點選該 API ，可以看到詳細的輸入引數，點選 API 介面右邊的 Try it out ，還可以對介面進行實時測試，是不是覺得有一中連單元測試都免了的感覺。

• 在上圖中，紅圈部分是我們編寫的 xml 註釋，可以看到，都被完整的抓取並顯示出來了

3. 定義 API 分組

• 上面是預設的 API 文件，在實際開發中，肯定需要對 API 進行分組和完善輸出引數給消費者，現在就來對 Controller 進行改進，首先是設定分組名稱

• 3.1 定義分組

    [Route("api/[controller]"), ApiExplorerSettings(GroupName = "演示分組")]
    [ApiController]
    public class ValuesController : ControllerBase

• 上面的程式碼在 ValuesController 上增加了一個特性 ApiExplorerSettings(GroupName = "演示分組"),這樣就完成了一個分組設定；不過，如果希望該分組能在瀏覽器中顯示，我們還需要在 Startup.cs 中定義的 docs 陣列中增加 "演示分組" 名稱

 static string[] docs = new[] { "未分類", "演示分組" };

4. 定義 API 介面友好名稱

• 4.1 下面對每個介面進行友好名稱顯示的定義，通過編寫 xml 註釋，並在 summary 節點書寫介面名稱，即可自動顯示到 API 文件上面

        /// <summary>
        ///  獲取陣列
        /// </summary>
        /// <remarks>
        /// <code>
        /// 輸出引數：["value1", "value2"]
        /// </code>
        /// </remarks>
        /// <returns></returns>
        [HttpGet]
        public ActionResult<IEnumerable<string>> Get()
        {
            return new string[] { "value1", "value2" };
        }

• 4.2 重新整理網頁，可以看到，介面友好名稱已經顯示出了了

結語

• Swagger 基礎應用可以幫助我們做到以下內容，現在就開始應用到程式中吧
• 自動生成 API 文件
• 對每個控制器進行分組
• 自動抓取開發人員編寫的 XML 註釋
• 在 API 文件介面進行即時測試
• 還有很多過濾等功能，下次有機會再試試

原始碼下載

https://files.cnblogs.com/files/viter/Ron.SwaggerTest.zip