【CSharp】在.NET6中使用Swagger-工具盒子

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

简介 {#%E7%AE%80%E4%BB%8B}

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

环境 {#%E7%8E%AF%E5%A2%83}

.NET6
ASP.NET Core Web API
Visual Studio 2022

使用 {#%E4%BD%BF%E7%94%A8}

创建Swagger {#%E5%88%9B%E5%BB%BAswagger}

通过创建项目时进行创建 {#%E9%80%9A%E8%BF%87%E5%88%9B%E5%BB%BA%E9%A1%B9%E7%9B%AE%E6%97%B6%E8%BF%9B%E8%A1%8C%E5%88%9B%E5%BB%BA}

创建一个新项目，在搜索中输入ASP.NET Core Web API进行搜索，然后选中第一个，点击"下一步"。
"项目名称"和"位置"根据自己项目实际进行修改，然后点击"下一步"。
框架选择.NET6，勾选上启用OpenAPI支持，然后点击"创建"。
创建好项目后，直接启动项目，默认会进入到Swagger UI，就能看到Web API默认生成的一个天气预报的接口。

通过NuGet创建 {#%E9%80%9A%E8%BF%87nuget%E5%88%9B%E5%BB%BA}

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

在Program.cs文件中添加

builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();
`f (app.Environment.IsDevelopment())
{
app.UseSwagger();
app.UseSwaggerUI();
}`

扩展 {#%E6%89%A9%E5%B1%95}

版本控制 {#%E7%89%88%E6%9C%AC%E6%8E%A7%E5%88%B6}

新建一个enum类，命名为ApiVersion.cs。
```
public enum ApiVersion
{
    V1,
    V2,
    V3
}
```

新建一个工具类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 =&gt;
            {
                options.SwaggerDoc(version, new OpenApiInfo()
                {
                    Title = $"{version}：Api文档",
                    Version = "v1",
                    Description = $"https://blog.uptoz.cn"
                });
            });

            #endregion 版本控制
    	});
    }



`}`

接口注释 {#%E6%8E%A5%E5%8F%A3%E6%B3%A8%E9%87%8A}

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

在前面新建的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 =&gt; o.RelativePath);
            }

            #endregion 显示注释
        });
    }

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



`}`

Token验证 {#token%E9%AA%8C%E8%AF%81}

在前面新建的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校验
        });
    }



`}`