基於.NetCore3.1系列 —— 使用Swagger作Api文檔 (下篇)

前言

         

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

  1. 已經有接口了，但如何添加註釋呢？

  2. 做爲接口使用者，咱們關心的是接口的返回內容和響應類型，那咱們如何定義描述響應類型呢？

  3. 在項目開發中，使用的實體類，又如何在Swagger中展現呢？

  4. 在部署項目，引用Swagger既有文檔又不須要額外部署，可是如何在開發環境中使用，而在生產環境中禁用呢？

開始

 1、爲接口方法添加註釋

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,顯示效果以下：

 

2、描述響應類型

  接口使用者最關心的就是接口的返回內容和相應類型啦。下面展現一下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";
        }

效果以下：

3、實體類展現添加註釋

 新建一個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;
        }

效果以下：

4、在生產環境中禁用

  能夠將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();
            });
        }

5、隱藏某些接口

 若是不想顯示某些接口，直接在controller 上，或者action 上，增長特性

        [ApiExplorerSettings(IgnoreApi = true)]

6、忽視Swagger註釋警告

 啓用 XML 註釋後會爲未記錄的公共類型和成員提供調試信息。若是出現不少警告信息  例如，如下消息指示違反警告代碼 1591：

 原來是swagger把一些 action 方法都經過xml文件配置了，若是你不想每個方法都這麼加註釋，能夠這麼配置，在當前項目進行配置，能夠忽略警告，記得在後邊加上分號 ;1591

常見錯誤

 在Swagger使用的時候報錯，沒法看到列表，這裏說下如何調試和主要問題：

1.找不到文件

請在瀏覽器 =》 F12 ==》 console 控制檯 ==》點擊錯誤信息地址

 

發現 是404 ，說明是找不到指定的文件，能夠存在如下狀況：

這是由於接口json文檔定義和調用不是一個

一、定義：

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

二、調用：

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. 關注公衆號能夠獲取資料

    下載源碼