介绍

Web API 的测试始终是一个挑战，因为它暴露了端点而不是 UI。测试此类内容可能依赖于第三方工具，例如 fiddler 和 Post-Man，以及 Web API 端点。Swagger 可以解决这个问题。它提供了 RESTful API 的 UI 表示，没有任何实现逻辑。它允许用户无需任何代码访问即可了解服务的功能，并且还减少了创建服务文档的时间。

Swagger 使用 Swagger 规范文件 (swagger.json) 生成 UI，该文件由 Swagger 工具根据服务代码生成。该文件描述了服务的能力；即，服务支持多少方法并提供有关方法参数的信息。Swagger UI 使用此文件生成客户端代码。以下是 swagger.json 文件的示例。

Swagger 可以使用 Swashbuckle.AspNetCore 和 NSwag 包在 ASP.net 核心 Web API 中实现。两者都是为 ASP.NET Core Web API 生成 Swagger 文档的开源项目。此外，NSwag 还提供了为 API 生成 TypeScript 客户端代码和 C# 服务器代码的方法。

使用 Swashbuckle.AspNetCore 在 ASP.net Core Web API 中配置 Swagger

以下是使用 Swashbuckle.AspNetCore 在 ASP.net Core Web API 中配置 Swagger 的步骤。

步骤 1 – 安装包 Swashbuckle.AspNetCore

使用以下命令，我们可以安装 Swashbuckle.AspNetCore 包。

PM> Install-Package Swashbuckle.AspNetCore

第 2 步 –配置 Swagger 中间件

要将 Swagger 中间添加到请求管道中，我们需要在启动类的 ConfigureService 方法中添加 AddSwaggerGen 方法。在这里，我们可以定义一个或多个 Swagger 文档。

Startup.cs

public void ConfigureServices(IServiceCollection services)  
{  
    services.AddMvc().SetCompatibilityVersion(CompatibilityVersion.Version_2_1);  
    services.AddSwaggerGen(c =>  
    {  
        c.SwaggerDoc("v1.0", new Info { Title = "My Demo API", Version = "1.0" });  
    });  
}

如果我们要启用这个中间件，需要在启动类的configure方法中调用UseSwagger方法。这里我们还需要配置 SwaggerEndpoint 来生成 UI。UseSwaggerUI 正在添加一个静态文件中间件来加载 swagger.json 文件。

public void Configure(IApplicationBuilder app, IHostingEnvironment env)  
{  
    if (env.IsDevelopment())  
    {  
        app.UseDeveloperExceptionPage();  
    }  
    else  
    {  
        app.UseHsts();  
    }  
  
    app.UseHttpsRedirection();  
  
    app.UseSwagger();  
    app.UseSwaggerUI(c =>  
    {  
        c.SwaggerEndpoint("/swagger/v1.0/swagger.json", "My Demo API (V 1.0)");  
    });  
    app.UseMvc();  
}

设置 Swagger 需要上述步骤。如果我们想使用 Visual Studio 在开发环境中启动 Swagger，还需要再做一项更改。要设置 Swagger UI，请转到项目属性 – 调试选项卡并将 Launch Browser 值更改为“swagger”。

当我们运行应用程序时，我们可以看到 ValuesContoller 的以下 Swagger UI。

正如我们在这里看到的，它为每个 HTTP 动词使用不同的颜色代码。当我们单击任何操作方法时，它会询问参数详细信息，当我们单击执行按钮时，它将向 Web API 发送请求。

Swagger 需要最低配置来测试我们的 Web API。它还在生成 UI 时显示 XML 注释，但这需要一些配置。

.net /.net core框架提供了一种为文档编写 XML 注释的方法。在 .net core 中，我们可以通过在项目属性窗口的构建选项卡下设置“XML 文档文件”属性来启用 XML 注释。

Swagger UI 默认不显示此文档。我们需要将路径传递给 IncludeXMLComments。

public void ConfigureServices(IServiceCollection services)  
{  
    services.AddMvc().SetCompatibilityVersion(CompatibilityVersion.Version_2_1);  
    services.AddSwaggerGen(c =>  
    {  
        c.SwaggerDoc("v1.0", new Info { Title = "My Demo API", Version = "1.0" });  
        c.IncludeXmlComments(System.IO.Path.Combine(System.AppContext.BaseDirectory, "SwaggerDemo.xml"));  
    });  
}

使用 NSwag 在 ASP.net Core Web API 中配置 Swagger

以下是使用 NSwag.AspNetCore 在 ASP.net Core Web API 中配置 Swagger 的步骤

步骤 1 –安装包 NSwag.AspNetCore

使用以下命令，我们可以安装 NSwag.AspNetCore 包

PM> Install-Package NSwag.AspNetCore

第 2 步 – 配置 Swagger 中间件

要将 Swagger 中间件添加到请求管道中，我们需要在启动类的 ConfigureService 方法中添加 AddSwaggerDocument 方法。此方法添加名称为“V1”的默认文档。如果我们要添加多个文档，请使用不同的文档名称多次调用此方法。

Startup.cs

public void ConfigureServices(IServiceCollection services)  
{  
    services.AddMvc().SetCompatibilityVersion(CompatibilityVersion.Version_2_1);  
    services.AddSwaggerDocument();  
}

如果要启用这个中间件，我们需要在启动类的configure方法中调用UseSwagger方法。此方法将默认路由添加为“/swagger/{documentName}/swagger.json” 此外，我们需要调用 UseSwaggerUi3 方法将 Swagger UI 添加到请求管道。

public void Configure(IApplicationBuilder app, IHostingEnvironment env)  
{  
    if (env.IsDevelopment())  
    {  
        app.UseDeveloperExceptionPage();  
    }  
    else  
    {  
        app.UseHsts();  
    }  
  
    app.UseHttpsRedirection();  
  
    app.UseSwagger();  
    app.UseSwaggerUi3();  
  
    app.UseMvc();  
}