前言

  回顧上一篇文章《使用Swagger做Api文件 》，文中介紹了在.net core 3.1中，利用Swagger輕量級框架，如何引入程式包，配置服務，註冊中介軟體，一步一步的實現，最終實現生產自動生產API介面說明文件。文中結尾也留下了一個讓大家思考的問題。在這裡，我們重新回顧一下這幾個問題

開始

 一、為介面方法添加註釋

1 . 按照下圖所示 連點三次 / 即可新增文件註釋

  如下所示

2.啟用XML 註釋

   右鍵web 專案名稱=>屬性=>生成，勾選“輸出”下面的“xml文件檔案”，系統會預設生成一個,如下圖所示

 3.配置服務

  在之前註冊的Swagger服務程式碼中，新增以下幾行程式碼，引入xml檔案

                var basePath = Path.GetDirectoryName(typeof(Program).Assembly.Location);//獲取應用程式所在目錄（絕對，不受工作目錄影響，建議採用此方法獲取路徑）
               //var basePath = AppContext.BaseDirectory;
                var xmlPath = Path.Combine(basePath, "XUnit.Core.xml");//這個就是剛剛配置的xml檔名
               // c.IncludeXmlComments(xmlPath);//預設的第二個引數是false,對方法的註釋
                 c.IncludeXmlComments(xmlPath,true); // 這個是controller的註釋

整體的程式碼如下：

        public void ConfigureServices(IServiceCollection services)
        {
            services.AddSwaggerGen(c =>
            {
                c.SwaggerDoc("V1", new OpenApiInfo
                {
                    Version = "V1",   //版本 
                    Title = $"XUnit.Core 介面文件-NetCore3.1",  //標題
                    Description = $"XUnit.Core Http API v1",    //描述
                    Contact = new OpenApiContact { Name = "艾三元", Email = "", Url = new Uri("http://i3yuan.cnblogs.com") },  
                    License = new OpenApiLicense { Name = "艾三元許可證", Url = new Uri("http://i3yuan.cnblogs.com") }
                });
                var basePath = Path.GetDirectoryName(typeof(Program).Assembly.Location);//獲取應用程式所在目錄（絕對，不受工作目錄影響，建議採用此方法獲取路徑）
               //var basePath = AppContext.BaseDirectory;
                var xmlPath = Path.Combine(basePath, "XUnit.Core.xml");//這個就是剛剛配置的xml檔名
                c.IncludeXmlComments(xmlPath);//預設的第二個引數是false,對方法的註釋
                // c.IncludeXmlComments(xmlPath,true); //這個是controller的註釋
            });
            services.AddControllers();
        }

 4.重新編譯執行

  檢視效果

注意：如果需要對控制器進行註釋說明如下，可以將

  c.IncludeXmlComments(xmlPath,true); 這個設定為true,顯示效果如下：

二、描述響應型別

  介面使用者最關心的就是介面的返回內容和相應型別啦。下面展示一下201和400一個簡單例子：

  我們需要在我們的方法上新增：[ProducesResponseType(201)][ProducesResponseType(400)]

  然後新增相應的狀態說明：<response code="201">返回value字串</response><response code="400">如果id為空</response>

  最終程式碼應該是這個樣子：

        /// <summary>
        /// values帶id引數的get
        /// </summary>
        /// <param name="id"></param>
        /// <response code="201">返回value字串</response>
        /// <response code="400">如果id為空</response>  
        /// <returns></returns>
        [HttpGet("{id}")]
        [ProducesResponseType(201)]
        [ProducesResponseType(400)]
        public string Get(int id)
        {
            return "value";
        }

效果如下：

三、實體類展示添加註釋

 新建一個Movie的實體類，MovieModel

    /// <summary>
    /// 這是電影實體類
    /// </summary>
    public class MovieModel
    {
        /// <summary>
        /// Id
        /// </summary>
        public int Id { get; set; }
        /// <summary>
        /// 影片名稱
        /// </summary>
        public string Name { get; set; }
        /// <summary>
        /// 型別
        /// </summary>
        public string Type { get; set; }
    }

在控制器中引入介面方法

        /// <summary>
        /// post方式提交電影名稱
        /// </summary>
        /// <param name="movie"></param>
        [HttpPost]
        public async Task<string> Post(MovieModel movie)
        {

            return movie.Name;
        }

效果如下：

四、在生產環境中禁用

  可以將Swagger的UI頁面配置在Configure的開發環境之中

放到if(env.IsDevelopment())即可。

        public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
        {
            if (env.IsDevelopment())
            {
                app.UseDeveloperExceptionPage();

                #region Swagger 只在開發環節中使用
                app.UseSwagger();
                app.UseSwaggerUI(c => {
                    c.SwaggerEndpoint($"/swagger/V1/swagger.json", $"XUnit.Core V1");
                    c.RoutePrefix = string.Empty;     //如果是為空 訪問路徑就為 根域名/index.html,注意localhost:8001/swagger是訪問不到的
                                                      //路徑配置，設定為空，表示直接在根域名（localhost:8001）訪問該檔案
                                                      // c.RoutePrefix = "swagger"; // 如果你想換一個路徑，直接寫名字即可，比如直接寫c.RoutePrefix = "swagger"; 則訪問路徑為 根域名/swagger/index.html
                });
                #endregion

            }
            app.UseRouting();

            app.UseAuthorization();

            app.UseEndpoints(endpoints =>
            {
                endpoints.MapControllers();
            });
        }

五、隱藏某些介面

 如果不想顯示某些介面，直接在controller 上，或者action 上，增加特性

        [ApiExplorerSettings(IgnoreApi = true)]

六、忽視Swagger註釋警告

 啟用 XML 註釋後會為未記錄的公共型別和成員提供除錯資訊。如果出現很多警告資訊  例如，以下訊息指示違反警告程式碼 1591：

 原來是swagger把一些 action 方法都通過xml檔案配置了，如果你不想每一個方法都這麼加註釋，可以這麼配置，在當前專案進行配置，可以忽略警告，記得在後邊加上分號 ;1591

常見錯誤

 在Swagger使用的時候報錯，無法看到列表，這裡說下如何除錯和主要問題：

1.找不到檔案

請在瀏覽器 =》 F12 ==》 console 控制檯 ==》點選錯誤資訊地址

發現 是404 ，說明是找不到指定的檔案，可以存在以下情況：

這是因為介面json文件定義和呼叫不是一個

1、定義：

ConfigureServices 方法中的  services.AddSwaggerGen 註冊的一個名字 c.SwaggerDoc("v1", 

2、呼叫：

Configure 方法中的 app.UseSwaggerUI(c =>   呼叫  c.SwaggerEndpoint("/swagger/V1/swagger.json；

看看兩者是否一致

 2. 500錯誤無法解析

直接連結http://localhost:xxxxx/swagger/v1/swagger.json，就能看到錯誤了

 這種可以存在以下情況：

1 . 介面請求的方式不明確： 少了[httpget]、[httpPost] 等，導致無法解析

總結

   1. 通過這一篇的整體學習，我們已經解決了上一篇文章留下的問題，也知道了怎樣更好的使用Swagger進行開發介面文件，更加方便快捷的使用

   2. 從上篇的引用配置啟動，到這一篇的升級改造，讓介面文件更加通俗易懂。

   3. 關注公眾號可以獲取資料

    下載原始碼