Asp.Netcore 使用swagger 來自動生成API文檔

一. 安裝nuget包

      搜索並安裝：Swashbuckle.AspNetCore的包

      結果如圖所示：

      

二.開始使用

    1.在Startup文件的 ConfigureSevers 裏面添加如下代碼：

        services.AddSwaggerGen(options =>
            {

                options.DocInclusionPredicate((docName, description) => true);//這兩句是支持動態Api的文檔
                options.CustomSchemaIds(type => type.FullName);//這兩句是支持動態Api的文檔
                options.SwaggerDoc("v1", new Info { Title = "My API", Version = "v1" });

                var basePath = Path.GetDirectoryName(typeof(Program).Assembly.Location);//獲取代碼運行的相對路徑
                options.IncludeXmlComments(Path.Combine(basePath, "Api.xml"), true);//插入代碼上的註釋放入Swagger
            });

        這裏需要添加

               using Swashbuckle.AspNetCore.Swagger;

     2.在Startup文件的Configure 裏面添加如下代碼：

           app.UseSwagger();
            app.UseSwaggerUI(option =>
            {
                option.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
            });

三.啓動項目即可使用。

     默認路由：https://localhost:【端口號】/swagger

    如下圖所示：

注意事項：

所有Controller和方法必須要有 Route ，也可以簡寫 [HttpGet("test")].如下圖所示

如果不寫會出現錯誤：  Not Found /swagger/v1/swagger.json   如下圖所示

四.顯示c#代碼的註釋

     1.打開用戶屬性 選到生成欄，如下圖所示，添加取消警告碼：1591，設置xml文檔文件存儲路徑

2.配置啓動Swagger時使用xml文檔，如下圖所示

3.這樣swagger上就會顯示c#代碼裏面寫的註釋，如下圖所示：

   注：如果需要顯示類的註釋時，如下修改注入文檔的方法

     如下：

         

4.註釋標準寫法 如下所示

        /// <summary>
        /// 封裝後的linq的查詢方式
        /// </summary>
        /// <typeparam name="T">要查詢和返回的Json</typeparam>
        /// <param name="indexName">index的名稱</param>
        /// <param name="typeName">type的名稱</param>
        /// <param name="selector">linq內容</param>
        /// <response code="200">返回值時泛型的List</response>
        public async Task<List<T>> SearchAsync<T>(string indexName, string typeName, Func<QueryContainerDescriptor<T>, QueryContainer> selector = null) where T : class
        {
            var list = await ElasticLinqClient.SearchAsync<T>(option => option.Index(indexName.ToLower()).Type(typeName).Query(selector));
            return list.Documents.ToList();
        }