Swagger UI in AspNetCore WebAPI

提示：扫一扫查出行
【扫一扫了解最新限行尾号】
复制提示

Swagger其实包含了三个部分，分别是Swagger Editor文档接口编辑器，根据接口文档生成code的Swagger Codegen，以及生成在线文档的Swagger UI。
在AspNetCore中通常使用Microsoft封装的Swashbuckle来使用Swagger UI，这是一个AspNetCore的中间件。和其他中间件一样都是分为register和use两个部分。Swagger UI主要通过将特殊特性标注过的API信息生成一个OpenAPI的文档，再将文档上的信息已网页的形式显示给用户。

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禁掉。）

MapType

很多时候，json的类型会有自定义的转化，这个时候需要使用MapType来让Swagger知道这个转化。

举一个PhoneNumber的例子：

public class PhoneNumber
{
public string CountryCode { get; set; } public string AreaCode { get; set; } public string SubscriberId { get; set; }
}

[HttpGet("PhoneNumber")]
public PhoneNumber GetPhoneNumber()
{
return new PhoneNumber()
{
AreaCode = "",
CountryCode = "",
SubscriberId = ""
};
}

如果在AddSwaggerGen中使用了

c.MapType<PhoneNumber>(() => new Schema { Type = "string" });

生成的json的response中就从PhoneNumber类变成了string。

"/market/PhoneNumber": {
"get": {
"tags": [
"Market"
],
"operationId": "GetPhoneNumber",
"consumes": [],
"produces": [
"text/plain",
"application/json",
"text/json"
],
"parameters": [],
"responses": {
"": {
"description": "Success",
"schema": {
"type": "string"
}
}
}
}
}

如果去掉，是这样的。

Use

RouteTemplate

UseSwagger中配置Swagger页面路由信息。默认情况下是swagger/{documentName}/swagger.json

RoutePrefix

类似SharePoint中的host name，默认为swagger，如果不需要可以设置为“”。

SwaggerEndpoint

OpenAPI文件的访问URL，这个url和RouteTemplate以及SwaggerDoc的name一定要一致，不然就会有page not found的错。从浏览器访问json文件的时候url中的document name是区分大小写的。
当请求OpenAPI文件的时候，会从SwaggerEndpoint配置的url中配合RouteTemplate一起解析document的name。
下面是RouteTemplate的配置：

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

解析document name的过程。

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