简介

Swagger 是一个开放源代码的框架，用于生成 API 文档和客户端代码，用于 RESTful API。在 .NET 6 中，Swagger 通常与 OpenAPI Specification 一起使用，后者是一个更现代的规范，用于描述 RESTful API

环境

  • .NET6

  • ASP.NET Core Web API

  • Visual Studio 2022

使用

创建Swagger

通过创建项目时进行创建

  1. 创建一个新项目，在搜索中输入ASP.NET Core Web API​进行搜索，然后选中第一个，点击“下一步”。

  2. “项目名称”和“位置”根据自己项目实际进行修改，然后点击“下一步”。

  3. 框架选择.NET6​，勾选上启用OpenAPI支持​，然后点击“创建”。

  4. 创建好项目后，直接启动项目，默认会进入到Swagger UI，就能看到Web API默认生成的一个天气预报的接口。

通过NuGet创建

  1. 在NuGet中搜索Swashbuckle.AspNetCore​，并安装第一个。

  2. 在Program.cs文件中添加

    builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();

f (app.Environment.IsDevelopment())
{
    app.UseSwagger();
    app.UseSwaggerUI();
}

扩展

版本控制

  1. 新建一个enum​类，命名为ApiVersion.cs​。

    public enum ApiVersion
{
    V1,
    V2,
    V3
}

  1. 新建一个工具类SwaggerExtension.cs​。

    public static class SwaggerExtension
{
    public static void AddSwaggerGenExt(this WebApplicationBuilder builder)
    {
        builder.Services.AddEndpointsApiExplorer();
        builder.Services.AddSwaggerGen(options =>
        {
            #region 版本控制

            typeof(ApiVersion).GetEnumNames().ToList().ForEach(version =>
            {
                options.SwaggerDoc(version, new OpenApiInfo()
                {
                    Title = $"{version}：Api文档",
                    Version = "v1",
                    Description = $"https://blog.uptoz.cn"
                });
            });

            #endregion 版本控制
    	});
	}
}

接口注释

  1. 在项目属性中找到“生成”内的“输出”，然后将“文档文件”的“生成包含API文档的文件”给勾选上，最后保存并生成一下。

    ​​

  2. 在前面新建的SwaggerExtension​类中增加以下代码

    请将“project-name”替换成你项目实际名称。

    public static class SwaggerExtension
{
    public static void AddSwaggerGenExt(this WebApplicationBuilder builder)
    {
        builder.Services.AddEndpointsApiExplorer();
        builder.Services.AddSwaggerGen(options =>
        {
            #region 显示注释

            {
                var file = Path.Combine(AppContext.BaseDirectory, "project-name.xml");
                options.IncludeXmlComments(file, true);
                options.OrderActionsBy(o => o.RelativePath);
            }

            #endregion 显示注释
        });
    }

    /// <summary> Swagger中间件配置 </summary>
    /// <param name="app"> </param>
    public static void UseSwaggerExt(this WebApplication app)
    {
        app.UseSwagger();
        app.UseSwaggerUI(options =>
        {
            typeof(ApiVersion).GetEnumNames().ToList().ForEach(version =>
            {
                options.SwaggerEndpoint($"/swagger/{version}/swagger.json", $"{version} API");
            });
        });
    }
}

Token验证

  1. 在前面新建的SwaggerExtension​类中增加以下代码

    public static class SwaggerExtension
{
    public static void AddSwaggerGenExt(this WebApplicationBuilder builder)
    {
        builder.Services.AddEndpointsApiExplorer();
        builder.Services.AddSwaggerGen(options =>
        {
         	#region Token校验

            options.AddSecurityDefinition("Bearer", new OpenApiSecurityScheme
            {
            	Description = "请输入Toke，格式为 Beare xxxxxxx",
            	Name = "Authorization",
            	In = ParameterLocation.Header,
            	Type = SecuritySchemeType.ApiKey,
            	BearerFormat = "JWT",
            	Scheme = "Bearer"
            });

            options.AddSecurityRequirement(new OpenApiSecurityRequirement
            {
            	{
                	new OpenApiSecurityScheme
                    {
                    	Reference = new OpenApiReference()
                        {
                        	Type = ReferenceType.SecurityScheme,
                            Id ="Bearer"
                        }
                    },
                    new string[] {}
                 }
            });

            #endregion Token校验
        });
    }
}