.Net項目使用Swagger

• Swagger簡述
• • 項目引用
  • 配置Swagger
  • 生成項目
  • 官方文檔：

Swagger簡述

Swagger (OpenAPI) 是一個與語言無關的規範，用于描述 REST API。 它使計算機和使用者無需直接通路源代碼即可了解 REST API 的功能。 
Swagger 項目已于 2015 年捐贈給 OpenAPI 計劃，自此它被稱為 OpenAPI。 這兩個名稱可互換使用。 不過，“OpenAPI”指的是規範。 “Swagger”指的是來自使用 OpenAPI 規範的 SmartBear 的開放源代碼和商業産品系列。
           

.NET 的兩個主要 OpenAPI 實作是 Swashbuckle 和 NSwag

本文章項目使用的是Swashbuckle來進行的操作，NSwag有一系列生成代碼的功能，感興趣的可以去看看官方文檔

項目引用

從“管理 NuGet 程式包”對話框中：

右鍵單擊“解決方案資料總管” > “管理 NuGet 包”中的項目

在搜尋框中輸入“Swashbuckle.AspNetCore”

從“浏覽”頁籤中選擇最新的“Swashbuckle.AspNetCore”包，然後單擊“安裝”

沒有swaggerGen還需要安裝"Swashbuckle.AspNetCore.SwaggerGen"

配置Swagger

将 Swagger 添加到 Startup.ConfigureServices 方法中的服務集合中：

public void ConfigureServices(IServiceCollection services)
{
    services.AddControllers();
        //注冊Swagger生成器
            services.AddSwaggerGen(config =>
            {
                config.SwaggerDoc("v1", new OpenApiInfo { Title = "SimpleBlog.WebApi", Version = "v1" });
                // 為 Swagger JSON and UI設定xml文檔注釋路徑
                var basePath = Path.GetDirectoryName(typeof(Program).Assembly.Location);//擷取應用程式所在目錄（絕對，不受工作目錄影響，建議采用此方法擷取路徑）
                var xmlPath = Path.Combine(basePath, "SimpleBlog.xml");//接口action顯示注釋
                //var xmlPath_entity = Path.Combine(basePath, "實體類庫.xml");//分層實體顯示注釋
                config.IncludeXmlComments(xmlPath);
                //config.IncludeXmlComments(xmlPath_entity);
            });
}
           

在 Startup.Configure 方法中，添加為生成的 JSON 文檔和 Swagger UI 提供服務的中間件

//使中間件能夠将生成的Swagger作為JSON端點。
            app.UseSwagger();
            //使中間件服務于swagger ui
            app.UseSwaggerUI(c =>
              {
                  c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
                  //在應用根目錄(localhost:<port>/)處提Swagger UI,根據需求決定
                  c.RoutePrefix = string.Empty;
              });
           

生成項目

啟動項目可以在

http://localhost:/swagger/v1/swagger.json 通路swagger檔案

http://localhost:/swagger 通路swaggerUI

配置了根目錄通路可以直接http://localhost:通路

啟動沒有通路到json檔案可以 在項目上右鍵–屬性–生成–輸出–XML文檔檔案上打√

一個簡單的swagger 配置就完成了，更多進階歡迎大家加群溝通交流

官方文檔：

https://docs.microsoft.com/zh-cn/aspnet/core/tutorials/web-api-help-pages-using-swagger?view=aspnetcore-3.1