本文最后更新于 2024-05-08,文章可能存在过时内容,如有过时内容欢迎留言或者联系我进行反馈。

简介

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校验
            });
        }
    }