Swagger UI in AspNetCore WebAPI

Swagger其實包含了三個部分，分別是Swagger Editor文檔介面編輯器，根據介面文檔生成code的Swagger Codegen，以及生成線上文檔的Swagger UI。
在AspNetCore中通常使用Microsoft封裝的Swashbuckle來使用Swagger UI，這是一個AspNetCore的中間件。和其他中間件一樣都是分為register和use兩個部分。

Installation

VS中很簡單，直接用NuGet安裝Swashbuckle.AspNetCore即可。

 或者使用命令行： dotnet add package --version xxx Swashbuckle.AspNetCore

Register

 所有Swagger UI註冊的configue相關的內容都放在AddSwaggerGen這個方法裡面：

namespace Microsoft.Extensions.DependencyInjection
{
    public static class SwaggerGenServiceCollectionExtensions
    {
        public static IServiceCollection AddSwaggerGen(this IServiceCollection services, Action<SwaggerGenOptions> setupAction = null);
        public static void ConfigureSwaggerGen(this IServiceCollection services, Action<SwaggerGenOptions> setupAction);
    }
}

AddSwaggerGen這個方法主要用戶註冊中間件的時候添加一些參數，其中重要的有：
SwaggerDoc：添加一個swagger document，主要用戶存儲生成出來的OpenAPI文檔。以及一些文檔基本信息，如：作者、描述、license等。
XXXFilter：自定義filter，XXX為Swagger中的對象，當XXX創建完成後，filter可以定義操作對XXX進行處理。
AddSecurityDefinition和AddSecurityRequirement：用於給Swagger添加驗證的部分。
IncludeXmlComments：為OpenAPI提供註釋內容的xml，需要在IDE裡面配置生成對應的XML文件。（當vs中使用生成xml文檔文件這個功能的時候，如果有方法沒有添加註釋，vs會有提示，如果要避免這個提示，可以在下圖中的Suppress warnings中把1591禁掉。）

 Use

RouteTemplate：UseSwagger中配置Swagger頁面路由信息。
RoutePrefix：類似SharePoint中的host name，預設為swagger，如果不需要可以設置為“”。
SwaggerEndpoint：OpenAPI文件的訪問URL，這個url和RouteTemplate以及SwaggerDoc的name一定要一致，不然就會有page not found的錯。
當請求OpenAPI文件的時候，會從SwaggerEndpoint配置的url中配合RouteTemplate一起解析document的name。
下麵是RouteTemplate的配置：

1 app.UseSwagger(option => 
2 {
3 　　option.RouteTemplate = string.Format("{0}/{1}", prefix, "{documentName}/swagger.json");
4 });

解析document name的過程。

 1 private bool RequestingSwaggerDocument(HttpRequest request, out string documentName)
 2 {
 3　　　documentName = null;
 4 　　if (request.Method != "GET") return false;
 5 
 6 　　var routeValues = new RouteValueDictionary();
 7 　　if (!_requestMatcher.TryMatch(request.Path, routeValues) || !routeValues.ContainsKey("documentName")) return false;
 8 
 9 　　documentName = routeValues["documentName"].ToString();
10 　　return true;
11 }