使用 Swagger 测试您的 ASP.NET Core Web API

作者 : 慕源网 本文共3238个字,预计阅读时间需要9分钟 发布时间: 2021-10-31 共229人阅读

介绍

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

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

使用 Swagger 测试您的 ASP.NET Core Web API

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 包。

  1. 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”。

使用 Swagger 测试您的 ASP.NET Core Web API

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

使用 Swagger 测试您的 ASP.NET Core Web API

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

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

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

使用 Swagger 测试您的 ASP.NET Core Web API

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"));  
    });  
}  

使用 Swagger 测试您的 ASP.NET Core Web API

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

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

步骤 1  –安装包 NSwag.AspNetCore

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

  1. 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();  
}  

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

使用 Swagger 测试您的 ASP.NET Core Web API

概括

Swagger 帮助我们在没有任何第三方工具和自定义代码的情况下测试我们的 Web API。在本文中,我解释了如何使用 Swashbuckle 和 NSwag 配置 Swagger。

您可以从此处的 GitHub 链接查看或下载源代码。


慕源网 » 使用 Swagger 测试您的 ASP.NET Core Web API

常见问题FAQ

程序仅供学习研究,请勿用于非法用途,不得违反国家法律,否则后果自负,一切法律责任与本站无关。
请仔细阅读以上条款再购买,拍下即代表同意条款并遵守约定,谢谢大家支持理解!

发表评论

开通VIP 享更多特权,建议使用QQ登录