什麼是Swagger?
說swagger 之前，我們先說一下OpenApi 規範。
OpenApi 是一種和語言無關的用於描述RESTAPIs 介面功能的一種規範，對RESTAPIs 介面的描述包括： 介面引數資訊、介面返回值資訊、api 功能描述、請求路徑等。
這裡我們說OpenApi 只是一種規範，既然是一種規範，就必然有相應的實現，Swagger 就是其中一個實現了Open Api 規範的工具。
.net 中RESTAPIs的代表便是 web api ，並且.net 針對Web Api 也有相應的Swagger 實現，主要有：Swashbuckle 和 NSwag，本文主要講解如何通過 Swashbuckle庫 將SwaggerUI整合到asp.net core專案中去，並快速生成asp.net web api 介面文件。
基本原理分析
在開始進入正題前，我們先看下我的 web api 示例站點中快速整合swagger ui 後的效果，並記住下面提到的 SwaggerUI 介面 和 OpenApi Json 資訊 兩個關鍵詞，因為後面會多次提到這兩個詞語。
SwaggerUI 介面如下圖：
OpenApi Json 資訊如下（該Json資訊描述了web api 所有介面，按照OpenApi規範生成）：
大致的原理就是，當我們瀏覽器中輸入：http://localhost:5000/swagger/index.html 請求SwaggerUI 頁面，SwaggerUI 中介軟體攔截到這個請求後，讀取內建SwaggerUI 頁面內容並響應給瀏覽器,瀏覽器再發起一個非同步請求去請求OpenApi Json 資訊，然後根據OpenApi Json 資訊生成上面第一張圖中所有的介面資訊，我們可以通過瀏覽器的開發人員工具看到這個請求。
OK，瞭解完SwaggerUI 的基本原理後，下面我們來講解如何快速將SwaggerUI 整合到 Web Api 專案中去。
安裝swagger相關nuget包
在需要整合swagger的專案中安裝nuget 包：Swashbuckle.AspNetCore
注入SwaggerAPI文件生成服務，新增SwaggerUI 響應中介軟體
開啟SwaggerDemo下的Startup.cs檔案，修改Configuservice 方法，將API文件生成服務新增到依賴注入容器中。
public void ConfigureServices(IServiceCollection services)
{
//這裡將OpenApi Json 資訊生成服務新增到依賴注入容器中，負責根據web api 的定義生成相應的OpenApi Json 資訊。
services.AddSwaggerGen();
services.AddControllersWithViews();
}
修改Startup.cs 下的 Configure 方法，將Swagger UI 請求攔截中介軟體、OpenApi Json 資訊請求攔截中介軟體加入到請求中介軟體管道列表中去。
public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
if (env.IsDevelopment())
{
app.UseDeveloperExceptionPage();
}
else
{
app.UseExceptionHandler("/Home/Error");
}
app.UseStaticFiles();
//UseSwagger新增了一箇中介軟體，這個中介軟體主要是攔截 瀏覽器中傳送過來的 獲取OpenApi Json 資訊的HTTP請求，並把WebApi 描述資訊返回給SwaggerUI，上圖中，我麼可以看到預設請求OpenApi Json 資訊的http地址是：http://localhost:5000/swagger/v1/swagger.json
app.UseSwagger();
//UseSwaggerUI 新增了一箇中介軟體，主要用於攔截SwaggerUI介面的訪問請求，並根據OpenApi Json 資訊動態生成介面列表，在上面的基本原理講述中，預設請求SwaggerUI 介面的http地址是：http://localhost:5000/swagger/index.html
app.UseSwaggerUI((options) =>
{
//SwaggerEndPoint 方法用於告訴SwaggerUI 請求哪個地址來獲取OpenApi Json 資訊，後面我們會講解如何自定義這個路徑。
options.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
});
app.UseRouting();
app.UseAuthorization();
app.UseEndpoints(endpoints =>
{
endpoints.MapControllerRoute(
name: "default",
pattern: "{controller=Home}/{action=Index}/{id?}");
});
}
OK，至此，SwaggerUI 就已經整合到了我們的WebApi 專案中去了，如果不出意外，那麼可以正常看到我上面 基本原理分析中提到的效果圖了，是不是很簡單，下面我們來講解一些更深入一些的用法。
如何自定義OpenApi Json 資訊請求Http地址?
預設OpenApi Json 資訊的請求地址為：/swagger/v1/swagger.json,如果我們想換成其他地址，比如改成：/BlogApis/v1/swagger.json 該如何操作呢？
首先配置攔截SwaggerUI介面請求的中介軟體，告訴SwaggerUI 從哪個地址去請求獲取 OpenApi Json 資訊。
app.UseSwaggerUI((options) =>
{
//options.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
//這裡告訴SwaggerUI從/BogApis/v1/swagger.json 獲取 OpenApi Json 資訊。
options.SwaggerEndpoint("/BlogApis/v1/swagger.json", "BlogApis");
}); 然後配置攔截OpenAPI Json 資訊的中介軟體，重新定義OpenApi Json資訊的請求路徑格式，如下：
app.UseSwagger(swaggerOptions =>
{
//告訴OpenApi Json 資訊請求攔截中介軟體，收到以下格式的請求時返回OpenApi Json資訊
//注意：路徑中必須包含: {documentName}，Swagger 中介軟體從請求路徑中{documentName}佔位符位置提取出api 文件名稱，以便顯示分組到該文件名稱下的
//所有api資訊。
swaggerOptions.RouteTemplate = "/BlogApis/{documentName}/swagger.json";
});順便提一下，通過檢視Swagger 原始碼，我們可以看到預設的OpenApi Json解析路由就是 swagger/{documentName}/swagger.json ，這就是為什麼我們一開始預設必須使用 /swagger/v1/swagger.json 格式去請求OpenApi Json 資訊的原因。
如何在SwaggerUI 中分組展示指定的API?
上面我們在 OpenApi Json 請求地址的解析路由中提到了必須包含{documentName}引數，比如：/BlogApis/{documentName}/swagger.json,同時上面也提到了OpenApi Json 資訊請求地址和這個路由是一一對應的，如：我們上面定義的OpenApi Json 資訊的請求地址是：/BlogApis/v1/swagger.json，當瀏覽器訪問SwaggerUI 頁面並請求 /BlogApis/v1/swagger.json 地址時，根據路由模板：/BlogApis/{documentName}/swagger.json 從OpenApi Json 請求地址的第二段中提取出v1作為 api 文件名稱，然後預設載入出所有 分組名稱為 v1 或者 未定義分組名稱的API 資訊，並顯示，那麼我們如何通過documentName 對api 進行分組展示呢？
開啟Startup.cs ,找到 ConfigureServices 方法，新增如下程式碼：
services.AddSwaggerGen(options =>
{
//這裡我們將使用者相關的API分成一組,這裡的User就是文件名稱(documentName)
options.SwaggerDoc("User", new Microsoft.OpenApi.Models.OpenApiInfo()
{
Title = "使用者管理",
Version = "1.0"
});
//這裡我們將文章管理相關的API分成一組。
options.SwaggerDoc("Post", new Microsoft.OpenApi.Models.OpenApiInfo()
{
Title = "文章管理",
Version = "1.0"
});
//以下是設定SwaggerUI中所有Web Api 的引數註釋、返回值等資訊從哪裡獲取。
var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
options.IncludeXmlComments(xmlPath);
});找到Configure方法，按照如下配置：
app.UseSwaggerUI((options) =>
{
//options.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
//options.SwaggerEndpoint("/BlogApis/v1/swagger.json", "BlogApis");
//定義使用者管理相關API的OpenApi Json 資訊請求路徑。
options.SwaggerEndpoint("/BlogApis/User/swagger.json", "UserManagerApis");
//定義文章管理相關API的OpenApi Json 資訊請求路徑。
options.SwaggerEndpoint("/BlogApis/User/swagger.json", "PostManagerApis");
});分別在UserController 、 PostController 上面新增 [ApiExplorerSettings]特性，並設定分組名稱
[Route("api/[controller]"), ApiExplorerSettings(GroupName = "User")]
[ApiController]
public class UserController : ControllerBase
{
/// <summary>
/// 使用者登入
/// </summary>
/// <param name="userName">使用者名稱</param>
/// <param name="password">密碼</param>
/// <returns></returns>
[HttpPost]
[ProducesResponseType(200, Type = typeof(UserInfo))]
public UserInfo Login([FromForm] string userName, [FromForm] string password)
{
if (userName == "chenxin" && password == "123456")
{
return new UserInfo() { UserName = "chenxin", Age = 31 };
}
return null;
}
[HttpGet]
public List<UserInfo> GetAllUsers()
{
return new List<UserInfo>()
{
new UserInfo()
{
UserName="chenxin",
Age=31
},
new UserInfo()
{
UserName="zhangsan",
Age=35
}
};
} [Route("api/{controller}")]
[ApiExplorerSettings(GroupName = "Post")]
public class PostController : ControllerBase
{
/// <summary>
/// 獲取所有文章
/// </summary>
/// <returns></returns>
[HttpGet]
public List<Post> GetAllPosts()
{
return new List<Post> { new Post()
{
Title="測試文章",
Content="測試內容..."
} };
}
}
public class Post
{
public string Title { get; set; }
public string Content { get; set; }
public DateTime PublishTime { get; set; } = DateTime.Now;
}按照上述步驟操作完成後，我們可以看到已經實現了API的分組。
好了，問題來了，為什麼預設沒有使用SwaggerDoc 方法定義任何文件名稱預設也能找到API資訊呢，其實還是Swagger 中介軟體預設給我們增加了一個名為v1的文件。
如何自定義SwaggerUI的請求路徑?
如果不想輸入 swagger/index.html 來訪問swaggerui ， 比如想改成 /BlogApisDocs,開啟Startup.cs 找到 Configure 方法，新增如下程式碼：
app.UseSwaggerUI((options) =>
{
//options.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
//options.SwaggerEndpoint("/BlogApis/v1/swagger.json", "BlogApis");
//定義使用者管理相關API的OpenApi Json 資訊請求路徑。
options.SwaggerEndpoint("/BlogApis/User/swagger.json", "UserManagerApis");
//定義文章管理相關API的OpenApi Json 資訊請求路徑。
options.SwaggerEndpoint("/BlogApis/User/swagger.json", "PostManagerApis");
//這裡我們告訴SwaggerUI 請求攔截中介軟體，當收到瀏覽器傳送過來的/BlogApisDocs 的請求則返回SwaggerUI 頁面。
options.RoutePrefix = "BlogApisDocs";
});
如何將API 方法註釋、引數註釋自動通過SwaggerUI展示？
開啟Startup.cs 找到 ConfigureServices方法增加如下程式碼：
services.AddSwaggerGen(options =>
{
//這裡我們將使用者相關的API分成一組。
options.SwaggerDoc("User", new Microsoft.OpenApi.Models.OpenApiInfo()
{
Title = "使用者管理",
Version = "1.0"
});
//這裡我們將文章管理相關的API分成一組。
options.SwaggerDoc("Post", new Microsoft.OpenApi.Models.OpenApiInfo()
{
Title = "文章管理",
Version = "1.0"
});
//以下是設定SwaggerUI中所有Web Api 的引數註釋、返回值等資訊從哪裡獲取。
//這裡表示從站點根目錄下的指定XML配置檔案中去讀取API的註釋資訊。
var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
options.IncludeXmlComments(xmlPath);
});然後需要設定WebApi 專案在生成專案時自動生成描述API資訊的XML檔案，並需要將生成的XML配置檔案SwaggerDemo.xml 設定為始終複製到輸出目錄：
好了，基本用法就講到這裡了，本文主要講解了如何對API進行分組，這裡僅僅是舉了一個按照API功能進行分組的例子，其實在實際開發中，要按照何種方式分組，可以按照需求靈活定義，比如按照API版本進行分組。
如果您在閱讀本文的過程中有任何疑問，歡迎給我的個人部落格：http://www.lovecoding.com.cn 留言，看到會及時回覆！