.NETCore 中配置 Swagger

发表于 分类于 ， ， 本文字数： 1.8k 阅读时长 ≈ 2 分钟

swagger

官方文档写得非常详细，本文只列出一些常用配置，方便拷贝进行快速配置使用。

定义

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
builder.services.AddSwaggerGen(swaggerOptions =>
{
    // 配置文档信息
    swaggerOptions.SwaggerDoc("v1", new OpenApiInfo()
    {
        Title = "WowToolAPI",
        Contact = new OpenApiContact()
        {
            Name = "galens",
            Url = new Uri("https://galens.uamazing.cn"),
            Email = "[email protected]"
        }
    });

    // Set the comments path for the Swagger JSON and UI.
    // 需要打开生成API文档功能
    var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
    var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
    swaggerOptions.IncludeXmlComments(xmlPath);

    // Bearer 的scheme定义
    var securityScheme = new OpenApiSecurityScheme()
    {
        Description = "JWT Authorization header using the Bearer scheme. Example: \"Authorization: Bearer {token}\"",
        Name = "Authorization",
        //参数添加在头部
        In = ParameterLocation.Header,
        //使用Authorize头部
        Type = SecuritySchemeType.Http,
        //内容为以 bearer开头
        Scheme = "bearer",
        BearerFormat = "JWT"
    };

    //把所有方法配置为增加bearer头部信息
    var securityRequirement = new OpenApiSecurityRequirement
    {
        {
            new OpenApiSecurityScheme
            {
               Reference = new OpenApiReference
               {
                   Type = ReferenceType.SecurityScheme,
                   Id = "bearerAuth"
               }
            },
            Array.Empty<string>()
        }
    };

    //注册到swagger中
    swaggerOptions.AddSecurityDefinition("bearerAuth", securityScheme);
    swaggerOptions.AddSecurityRequirement(securityRequirement);
});

在开发环境中启用

1
2
3
4
5
if (app.Environment.IsDevelopment())
{
    app.UseSwagger();
    app.UseSwaggerUI();
}

打开生成 API 文档

在属性->生成->输出，勾选文档文件。生成包含 API 文档的 XML 说明文件。

美化界面

可以使用 IGeekFan.AspNetCore.Knife4jUI 进行美化，由于平时使用 Apifox 进行调试，Swagger 用得比较少，此处不详细展开介绍。

参考

Learn more about configuring Swagger/OpenAPI