ASP.NET Core Swashbuckle的使用配置及示例

1､Swashbuckle包含三个主要组件

1) Swashbuckle.AspNetCore.Swagger：Swagger对象模型和中间件，用于将SwaggerDocument对象公开为JSON端点。

2) Swashbuckle.AspNetCore.SwaggerGen：一个Swagger生成器，可SwaggerDocument直接从您的路线，控制器和模型构建对象。它通常与Swagger端点中间件结合使用，以自动公开Swagger JSON。

3) Swashbuckle.AspNetCore.SwaggerUI：Swagger UI工具的嵌入式版本。它解释Swagger JSON来构建丰富的，可定制的体验，以描述Web API功能。它包括用于公共方法的内置测试工具。

2､安装引用Swashbuckle

1）使用Nuget界面管理器

搜索"Swashbuckle.AspNetCore",在列表中找到它，点击"安装"

相关文档：VS(Visual Studio)中Nuget的使用

2）使用Package Manager命令安装

PM> Install-Package Swashbuckle.AspNetCore -Version 5.0.0

3）使用.NET CLI命令安装

> dotnet add TodoApi.csproj package Swashbuckle.AspNetCore -v 5.0.0

3､配置Swashbuckle(Swagger中间件)

1) 在Startup中，导入以下名称空间以使用OpenApiInfo类：

using Microsoft.OpenApi.Models;

2) 在Startup.ConfigureServices方法中将Swagger生成器添加到服务集合：

public void ConfigureServices(IServiceCollection services)
{
    services.AddDbContext<TodoContext>(opt =>
        opt.UseInMemoryDatabase("TodoList"));
    services.AddControllers();
    // Register the Swagger generator, defining 1 or more Swagger documents
    services.AddSwaggerGen(c =>
    {
        c.SwaggerDoc("v1", new OpenApiInfo { Title = "My API", Version = "v1" });
    });
}

3) 在该Startup.Configure方法中，启用用于提供生成的JSON文档和Swagger UI的中间件：

public void Configure(IApplicationBuilder app)
{
    // Enable middleware to serve generated Swagger as a JSON endpoint.
    app.UseSwagger();
    // Enable middleware to serve swagger-ui (HTML, JS, CSS, etc.),
    // specifying the Swagger JSON endpoint.
    app.UseSwaggerUI(c =>
    {
        c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
    });
    app.UseRouting();
    app.UseEndpoints(endpoints =>
    {
        endpoints.MapControllers();
    });
}

前面的UseSwaggerUI方法调用启用了“ 静态文件中间件”。如果目标是.NET Framework或.NET Core 1.x，则将Microsoft.AspNetCore.StaticFiles NuGet程序包添加到项目中。

启动应用程序，然后导航到http://localhost:/swagger/v1/swagger.json。生成的描述端点的文档如所示Swagger规范(swagger.json)

Swagger用户界面位于http://localhost:/swagger。通过Swagger UI探索API，并将其合并到其他程序中。

注意：

要在应用程序的根目录(http://localhost/)提供Swagger UI ，请将RoutePrefix属性设置为空字符串：

app.UseSwaggerUI(c =>
{
    c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
    c.RoutePrefix = string.Empty;
});

如果将目录与IIS或反向代理一起使用，请使用./前缀将Swagger端点设置为相对路径。例如，./swagger/v1/swagger.json。使用/swagger/v1/swagger.json指示应用程序在URL的真实根目录下查找JSON文件（如果使用，则加上路由前缀(RoutePrefix)）。例如，使用http://localhost://swagger/v1/swagger.json代替http://localhost:///swagger/v1/swagger.json。

相关文档：

ASP.NET Core Web API Swagger/OpenAPI Swashbuckle.AspNetCore NSwag介绍

getting-started-with-swashbuckle