如何在 ASP.NET Core 中配置 Swagger？

Question

我想在我的项目中实现/配置 Swagger。

我已经安装了（Swashbuckle）包，这是 swagger 实现所必需的。

我应该在哪里添加 swagger 配置或者我应该包含哪个文件。

Answer 1

如果您要从正确的模板创建项目，它已经带有 Swagger 预设置。例如，您可以使用 ASP.NET Core Web API 模板（通过 IDE 或使用

dotnet new

命令 和

webapi

模板名称）。它包括（对于 .NET 7）：

• 预装软件包：

  <PackageReference Include="Microsoft.AspNetCore.OpenApi" Version="7.0.7"/>
  <PackageReference Include="Swashbuckle.AspNetCore" Version="6.5.0"/>
  

• Swagger 设置（在

  Program.cs

  中）：

  // ...
  builder.Services.AddEndpointsApiExplorer();
  builder.Services.AddSwaggerGen();
  
  // ...
  
  if (app.Environment.IsDevelopment()) // by default enabled only for dev.
  {
       app.UseSwagger();
       app.UseSwaggerUI();
  }
  

另请阅读：

• Swashbuckle.AspNetCore

  ：开始使用

Answer 2

.NET 7 WebAPI 项目，您需要在

Program.cs

文件上配置它。

您需要将 Swagger 生成器添加到服务集合中。

var builder = WebApplication.CreateBuilder(args);
//Add the Swagger generator to the services collection
builder.Services.AddSwaggerGen();

使用JWT授权配置Swagger的示例如下：

builder.Services.AddSwaggerGen(option =>
{
    option.SwaggerDoc("v1", new OpenApiInfo { Title = "Demo API", Version = "v1" });
    option.AddSecurityDefinition("Bearer", new OpenApiSecurityScheme
    {
        In = ParameterLocation.Header,
        Description = "Please enter a valid token",
        Name = "Authorization",
        Type = SecuritySchemeType.Http,
        BearerFormat = "JWT",
        Scheme = "Bearer"
    });
    option.AddSecurityRequirement(new OpenApiSecurityRequirement
    {
        {
            new OpenApiSecurityScheme
            {
                Reference = new OpenApiReference
                {
                    Type = ReferenceType.SecurityScheme,
                    Id = "Bearer"
                }
            },
            new string[]{ }
        }
    });
});

Answer 3

.net 9

不再支持

Swashbuckle

，他们建议我们升级到

NSwag

。并不复杂

dotnet add package NSwag.AspNetCore

然后像下面一样更改program.cs

....
builder.Services.AddOpenApiDocument();
....
if (app.Environment.IsDevelopment())
{
    // Add OpenAPI 3.0 document serving middleware
    // Available at: http://localhost:<port>/swagger/v1/swagger.json
    app.UseOpenApi();

    // Add web UIs to interact with the document
    // Available at: http://localhost:<port>/swagger
    app.UseSwaggerUi(); // UseSwaggerUI Protected by if (env.IsDevelopment())
}

这里是一个工作示例。

参考：

• https://github.com/dotnet/aspnetcore/issues/54599
• https://learn.microsoft.com/en-us/aspnet/core/tutorials/getting-started-with-nswag?view=aspnetcore-8.0&tabs=visual-studio