netcore使用Swagger生成接口文档

Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。

安装

1
dotnet add package Swashbuckle.AspNetCore

配置

Startup.cs

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
public void ConfigureServices(IServiceCollection services)
{
    // 注册Swagger服务
    option.SwaggerDoc("v1", new OpenApiInfo
    {
        Version = "v1",
        Title = "CoreWebApi",
        Description = "Document Api",
        Contact = new OpenApiContact
        {
            Name = "acgog",
            Email = "sacgog@aliyun.com",
            Url =new Uri("https://www.acgog.cn")
        }
    });
    // 使用反射获取xml文件。并构造出文件的路径
    var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
    var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
    // 启用xml注释. 该方法第二个参数启用控制器的注释，默认为false.
    option.IncludeXmlComments(xmlPath, true);
}
public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    app.UseSwagger();
    // 配置SwaggerUI
    app.UseSwaggerUI(c =>
    {
        c.SwaggerEndpoint("/swagger/v1/swagger.json", "CoreWebApi");
        c.RoutePrefix = "swagger";  //默认
        //c.RoutePrefix = string.Empty; 路由为空 首页
    });
}

启用XML注释

启用XML注释之后可以轻松映射到UI界面方便前端开发人员理解。
编辑****.csproj

1
2
3
4
<PropertyGroup>
    <GenerateDocumentationFile>true</GenerateDocumentationFile> 
    <NoWarn>$(NoWarn);1591</NoWarn>
</PropertyGroup>

这两句的大概意思就是启用XML注释，并忽略未写注释的警告。
不添加1591如果某个方法未写 “///“各式的注释，vs会有警示的消息。

JWT Authorize 验证

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
services.AddSwaggerGen(s =>
{
    s.SwaggerDoc("v1", new OpenApiInfo { Title = "My API", Version = "v1" });
    s.AddSecurityDefinition("Bearer", new OpenApiSecurityScheme()
    {
        Description = "在下框中输入请求头中需要添加Jwt授权Token：Bearer Token",
        Name = "Authorization",
        In = ParameterLocation.Header,
        Type = SecuritySchemeType.ApiKey,
        BearerFormat = "JWT",
        Scheme = "Bearer"
    });
    s.AddSecurityRequirement(new OpenApiSecurityRequirement{
        {
            new OpenApiSecurityScheme{
                Reference = new OpenApiReference {
                            Type = ReferenceType.SecurityScheme,
                            Id = "Bearer"}
           },new string[] { }
        }
    });
});

版本控制

nuget

1
Microsoft.AspNetCore.Mvc.Versioning

Startup

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
55
56
/// <summary>
/// Api版本信息
/// </summary>
private IApiVersionDescriptionProvider provider;
public void ConfigureServices(IServiceCollection services){

    services.AddApiVersioning(option =>{
        // 可选，为true时API返回支持的版本信息
        option.ReportApiVersions = true;
        // 不提供版本时，默认为1.0
        option.AssumeDefaultVersionWhenUnspecified = true;
        // 请求中未指定版本时默认为1.0
        option.DefaultApiVersion = new ApiVersion(1, 0);
    }).AddVersionedApiExplorer(option =>
    {　　　　　　　　　　// 版本名的格式：v+版本号
        option.GroupNameFormat = "'v'V";
        option.AssumeDefaultVersionWhenUnspecified = true;
    });
    // 注册Swagger服务
    services.AddSwaggerGen(c =>{
        // 多版本控制
        foreach (var item in provider.ApiVersionDescriptions)
        {
            // 添加文档信息
            c.SwaggerDoc(item.GroupName, new Info
            {
                Title = "CoreWebApi",
                Version = item.ApiVersion.ToString(),
                Description = "ASP.NET CORE WebApi",
                Contact = new Contact
                {
                    Name = "acgog",
                    Email = "sacgog@aliyun.com",
                    Url =new Uri("https://www.acgog.cn")
                }
            });
        }
    }
    this.provider = services.BuildServiceProvider().GetRequiredService<IApiVersionDescriptionProvider>();

}
public void Configure(IApplicationBuilder app, IWebHostEnvironment env){

    // 配置SwaggerUI
    app.UseSwaggerUI(c =>
    {
        foreach (var item in provider.ApiVersionDescriptions)
        {
            //c.SwaggerEndpoint("/swagger/v1/swagger.json", "CoreAPI"); 单版本
            c.SwaggerEndpoint($"/swagger/{item.GroupName}/swagger.json", "CoreAPI"+item.ApiVersion);
        }
        c.RoutePrefix = string.Empty;
    });
}

[ApiVersion("1.0")]

其他

注释

1
2
3
4
5
6
7
8
9
10
11
12
/// <summary>
/// xxxxxxxx
/// </summary>
/// <remarks>
/// 例子:
/// Get api/Values/1
/// </remarks>
/// <param name="id">xx</param>
/// <returns>xx</returns>  
public void Test(){

}