本文主要介绍ASP.NET Core中,API接口文档生成工具Swashbuckle(Swagger)的介绍,安装引用Swashbuckle的方法,以及使用和配置方法及示例。

1、Swashbuckle包含三个主要组件

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

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

3) Swashbuckle.AspNetCore.SwaggerUISwagger 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