asp.net core 一個中小型項目實戰的起手式——Swagger配置

一、Swagger是什麼

Swagger 是一款RESTFUL介面的、基於YAML、JSON語言的文檔線上自動生成、代碼自動生成的工具。

二、如何在項目中加入Swagger

• Swagger安裝引用

　　　　右鍵Web項目依賴項>管理NuGet程式包>在搜索框輸入"Swashbuckle.AspNetCore"，然後單擊安裝

• 添加並配置Swagger中間件

　　　　首先在Startup類中引入Swagger：

　　　　　　　　using Swashbuckle.AspNetCore.Swagger;

　　　　將 Swagger 生成器添加到ConfigureServices 方法中的服務集合中：

            //註冊Swagger生成器，定義一個和多個Swagger文檔
            services.AddSwaggerGen(p =>
            {
                p.SwaggerDoc("v1", new Info {Title = "數據管理器API文檔", Version = "V1"});
            });

　　　　在Configure方法中，啟用中間件為生成的JSON文檔和SwaggerUI提供服務：

            //啟用中間件服務生成Swagger作為JSON終結點
            app.UseSwagger();
            //啟用中間件服務對swagger-ui，指定Swagger JSON終結點
            app.UseSwaggerUI(p =>
            {
                p.SwaggerEndpoint("/swagger/v1/swagger.json", "數據管理器API文檔 v1"); 
            });

　　　　啟動應用，並跳轉到 http://localhost:<port>/swagger/v1/swagger.json 生成的描述終結點的文檔顯示如下json格式。

　　　　可在 /swagger 找到 Swagger UI。 通過 Swagger UI 瀏覽 API文檔，如下所示。

•  為介面方法提供註釋

　　首先右鍵【解決方案資源管理器】中的項目，然後選【屬性】

　　查看“生成”選項卡的【輸出】部分下的【XML 文檔文件】框

　　啟用 XML 註釋後會為未記錄的公共類型和成員提供調試信息。如果出現很多警告信息  例如，以下消息指示違反警告代碼 1591。可以在進位顯示警告中加入警告代碼，這樣不會再在錯誤列表中顯示1591類型的警告了。

在Swagger註冊服務中增加：

            //註冊Swagger生成器，定義一個和多個Swagger文檔
            services.AddSwaggerGen(p =>
            {
                p.SwaggerDoc("v1", new Info {Title = "數據管理器API文檔", Version = "V1"});

                // 為 Swagger JSON and UI設置xml文檔註釋路徑
                var basePath = Path.GetDirectoryName(typeof(Program).Assembly.Location);//獲取應用程式所在絕對目錄
                var xmlPath = Path.Combine(basePath, "DataManager.Web.xml");//此處的文件名要對應到項目屬性中生成的xml文件名
                p.IncludeXmlComments(xmlPath);
            });

在控制器目錄下新增一個WebApi測試控制器，測試下效果

    [Route("api/[controller]/[action]")]
    [ApiController]
    public class SwaggerTestController : ControllerBase
    {
        /// <summary>
        /// 這是一個Swagger測試介面
        /// </summary>
        /// <returns></returns>
        [HttpGet]
        public IActionResult Test()
        {
            return new JsonResult(new {key = "Name", value = "test"});
        }
    }

訪問/swagger:

好了，今天的在ASP.NET Core WebApi使用Swagger生成api說明文檔的教程就到這裡了。希望能夠對大家學習在ASP.NET Core中使用Swagger生成api文檔有所幫助！