基於.NetCore3.1搭建項目系列 —— 使用Swagger做Api文檔 (下篇)

-Advertisement-

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

前言

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

1. 已經有介面了，但如何添加註釋呢？ 2. 作為介面使用者，我們關心的是介面的返回內容和響應類型，那我們如何定義描述響應類型呢？ 3. 在項目開發中，使用的實體類，又如何在Swagger中展示呢？ 4. 在部署項目，引用Swagger既有文檔又不需要額外部署，但是如何在開發環境中使用，而在生產環境中禁用呢？

開始

一、為介面方法添加註釋

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. 關註公眾號可以獲取資料

下載源碼

您的分享是我們最大的動力!