Asp.Net Core 輕鬆學-利用 Swagger 自動生成接口文檔

時間 2019-11-07

標籤 asp.net asp core 輕鬆利用 swagger 自動生成接口文檔欄目 ASP 简体版

原文原文鏈接

前言

目前市場上主流的開發模式，幾乎清一色的先後端分離方式，做爲服務端開發人員，咱們有義務提供給各個客戶端良好的開發文檔，以方便對接，減小溝通時間，提升開發效率；對於開發人員來講，編寫接口文檔須要消耗大量的時間，而且，手動編寫的文檔接口會因爲需求的頻繁變更變得難以維護，這就須要一個在接口開發階段能夠自動監測接口輸入參數，自動生成文檔的功能；因爲 Swagger 插件的出現，這項工做幾乎能夠實現徹底的自動化。html

1. 什麼是 Swagger

Swagger 是由 SmartBear 公司開發的一款 API 文檔自動化工具，其採用 Apache 2.0 免費開源受權協議，容許任何人無償使用該工具，利用 Swagger 的特性，能夠很方便在沒有任何實現邏輯的狀況下生成可視化和與API資源交互界面，Swagger 支持 API 分類導航，提供 API 測試套件，徹底的可定製化，對開發人員和 API 消費者都很是友好。git

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 進行改進，首先是設置分組名稱github
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" };
        }