摘要

在前后端分离、Restful API盛行的年代，完美的接口文档，成了交流的纽带。在项目中引入Swagger （也称为OpenAPI），是种不错的选择，它可以让接口数据可视化。下文将会演示

  • 利用Nswag如何生成Api文档

  • 利用NSwagStudio如何生成客户端代码,并且进行测试

什么是 Swagger/OpenAPI？

Swagger 是一个与语言无关的规范，用于描述 REST API。Swagger 项目已捐赠给 OpenAPI 计划，现在它被称为开放 API。这两个名称可互换使用，但 OpenAPI 是首选。它允许计算机和人员了解服务的功能，而无需直接访问实现（源代码、网络访问、文档）。其中一个目标是尽量减少连接取消关联的服务所需的工作量。另一个目标是减少准确记录服务所需的时间。

Nswag VS Swashbuckle？

.NET Swagger 实现类库有两个比较流行：

  • Swashbuckle.AspNetCore 是一个开源项目，用于生成 ASP.NET Core Web API 的 Swagger 文档。

  • NSwag 是另一个用于生成 Swagger 文档并将 Swagger UI 或 ReDoc 集成到 ASP.NET Core Web API 中的开源项目。此外，NSwag 还提供了为 API 生成 C# 和 TypeScript 客户端代码的方法。

 

为什么我在.NET core3.0中选择NSwag呢，NSwag比较活跃，一直在更新，功能也很强大，可以完美的代替Swashbuckle.AspNetCore具体可以参考：https://github.com/aspnet/AspNetCore.Docs/issues/4258

一、利用Nswag生成Api文档

步骤

  1. 创建Asp.NET Core Api项目，并且集成NSwag

  2. 配置项目

  3. 运行项目

创建Asp.NET Core Api项目，并且集成NSwag

我们将简单的创建一个ASP.NET core API项目。将其命名为“WebAPIwithSwg”。基于.NETcore3.0

安装nuget包NSwag.AspNetCore

接下来，在Startup.cs文件中配置Nswag服务和中间件。

在ConfigureServices方法中添加服务

复制代码
  public void ConfigureServices(IServiceCollection services)         {             services.AddControllers();             services.AddSwaggerDocument(); //注册Swagger 服务        }
复制代码
在Configure方法中添加Nswag中间件
复制代码
 public void Configure(IApplicationBuilder app, IWebHostEnvironment env)         {             if (env.IsDevelopment())             {                 app.UseDeveloperExceptionPage();             }             app.UseRouting();             app.UseAuthorization();             app.UseEndpoints(endpoints =>             {                 endpoints.MapControllers();             });             app.UseOpenApi(); //添加swagger生成api文档（默认路由文档 /swagger/v1/swagger.json）            app.UseSwaggerUi3();//添加Swagger UI到请求管道中(默认路由: /swagger).        }
复制代码
配置项目

运行项目

右键项目在浏览器中查看，查看swagger UI需要在url后面添加“/swagger”。本示例http://localhost:54117/swagger

二、利用NSwagStudio如何生成客户端代码,并且进行测试
提供GUI界面是NSwag的一大特点，只需要下载安装NSwagStudio，即可生成客户端代码。
步骤

  1. 现在安装NSwagStudio

  2. NSwagStudio配置，生成客户端代码

  3. 创建测试客户端项目