NSwag 和 ASP.NET Core 入门Get started with NSwag and ASP.NET Core

本文内容

作者：Christoph Nienaber、Rico Suter 和 Dave Brock

查看或下载示例代码（如何下载）

查看或下载示例代码（如何下载）

NSwag 提供了下列功能：

  • 能够使用 Swagger UI 和 Swagger 生成器。
  • 灵活的代码生成功能。

借助 NSwag，无需使用现有 API。也就是说，可使用包含 Swagger 的第三方 API，并生成客户端实现。使用 NSwag，可以加快开发周期，并轻松适应 API 更改。

注册 NSwag 中间件Register the NSwag middleware

注册 NSwag 中间件即可：

  • 生成已实现的 Web API 的 Swagger 规范。
  • 为 Swagger UI 提供服务以浏览和测试 Web API。

若要使用 NSwag ASP.NET Core 中间件，请安装 NSwag.AspNetCore NuGet 包。此包内的中间件可用于生成并提供Swagger 规范、Swagger UI（v2 和 v3）和 ReDoc UI。

若要安装 NSwag NuGet 包，请使用以下方法之一：

  • 从“程序包管理器控制台” 窗口：

    • 转到“视图” > “其他窗口” > “程序包管理器控制台”

    • 导航到包含 TodoApi.csproj 文件的目录

    • 请执行以下命令：

  1. Install-Package NSwag.AspNetCore

  • 从“管理 NuGet 程序包” 对话框中：

    • 右键单击“解决方案资源管理器” > “管理 NuGet 包”中的项目
    • 将“包源” 设置为“nuget.org”
    • 在搜索框中输入“NSwag.AspNetCore”
    • 从“浏览”选项卡中选择“NSwag.AspNetCore”包，然后单击“安装”
  • 右键单击“Solution Pad” > “添加包…” 中的“包” 文件夹
  • 将“添加包” 窗口的“源” 下拉列表设置为“nuget.org”
  • 在搜索框中输入“NSwag.AspNetCore”
  • 从结果窗格中选择“NSwag.AspNetCore”包，然后单击“添加包”

运行下面的命令：

  1. dotnet add TodoApi.csproj package NSwag.AspNetCore

添加并配置 Swagger 中间件Add and configure Swagger middleware

通过执行以下步骤，在 ASP.NET Core 应用中添加和配置 Swagger：

  • 在 Startup.ConfigureServices 方法中，注册所需的 Swagger 服务：
  1. public void ConfigureServices(IServiceCollection services)
  2. {
  3.     services.AddDbContext<TodoContext>(opt =>
  4.         opt.UseInMemoryDatabase("TodoList"));
  5.     services.AddMvc();
  7.     // Register the Swagger services
  8.     services.AddSwaggerDocument();
  9. }
  • 在 Startup.Configure 方法中，启用中间件为生成的 Swagger 规范和 Swagger UI 提供服务：
  1. public void Configure(IApplicationBuilder app)
  2. {
  3.     app.UseStaticFiles();
  5.     // Register the Swagger generator and the Swagger UI middlewares
  6.     app.UseOpenApi();
  7.     app.UseSwaggerUi3();
  9.     app.UseMvc();
  10. }

代码生成Code generation

若要利用 NSwag 的代码生成功能，可选择以下选项之一：

使用 NSwagStudio 生成代码Generate code with NSwagStudio

  • 按照 NSwagStudio GitHub 存储库中的说明操作，以安装 NSwagStudio。在 NSwag 发布页面上，可以下载无需安装和管理员权限即可启动的 xcopy 版本。

  • 启动 NSwagStudio，并在“Swagger 规范 URL” 文本框中输入 swagger.json 文件 URL。例如， http://localhost:44354/swagger/v1/swagger.json 。

  • 单击“创建本地副本” 按钮，以生成 Swagger 规范的 JSON 表示形式。

创建 Swagger 规范的本地副本

  • 在“输出” 区域中，单击选中“C# 客户端”复选框 。也可以选中“TypeScript 客户端” 或“C# Web API 控制器” ，具体视项目而定。如果选中“C# Web API 控制器” ，服务规范会重新生成服务，起到反向生成的作用。

  • 单击“生成输出” ，以生成 TodoApi.NSwag 项目的完整 C# 客户端实现。若要查看生成的客户端代码，请单击“C# 客户端”选项卡 ：

  1. //----------------------
  2. // <auto-generated>
  3. //     Generated using the NSwag toolchain v12.0.9.0 (NJsonSchema v9.13.10.0 (Newtonsoft.Json v11.0.0.0)) (http://NSwag.org)
  4. // </auto-generated>
  5. //----------------------
  7. namespace MyNamespace
  8. {
  9.     #pragma warning disable
  11.     [System.CodeDom.Compiler.GeneratedCode("NSwag", "12.0.9.0 (NJsonSchema v9.13.10.0 (Newtonsoft.Json v11.0.0.0))")]
  12.     public partial class TodoClient
  13.     {
  14.         private string _baseUrl = "https://localhost:44354";
  15.         private System.Net.Http.HttpClient _httpClient;
  16.         private System.Lazy<Newtonsoft.Json.JsonSerializerSettings> _settings;
  18.         public TodoClient(System.Net.Http.HttpClient httpClient)
  19.         {
  20.             _httpClient = httpClient;
  21.             _settings = new System.Lazy<Newtonsoft.Json.JsonSerializerSettings>(() =>
  22.             {
  23.                 var settings = new Newtonsoft.Json.JsonSerializerSettings();
  24.                 UpdateJsonSerializerSettings(settings);
  25.                 return settings;
  26.             });
  27.         }
  29.         public string BaseUrl
  30.         {
  31.             get { return _baseUrl; }
  32.             set { _baseUrl = value; }
  33.         }
  35.         // code omitted for brevity

提示

C# 客户端代码的生成依据是，“设置” 选项卡中的选择。修改设置以执行任务，例如默认命名空间重命名和同步方法生成。

  • 将生成的 C# 代码复制到使用 API 的客户端项目内的文件中。
  • 开始使用 Web API：
  1.  var todoClient = new TodoClient();
  3. // Gets all to-dos from the API
  4.  var allTodos = await todoClient.GetAllAsync();
  6.  // Create a new TodoItem, and save it via the API.
  7. var createdTodo = await todoClient.CreateAsync(new TodoItem());
  9. // Get a single to-do by ID
  10. var foundTodo = await todoClient.GetByIdAsync(1);

自定义 API 文档Customize API documentation

Swagger 提供用于记录对象模型以便于使用 Web API 的选项。

API 信息和说明API info and description

在 Startup.ConfigureServices 方法中，传递给 AddSwaggerDocument 方法的配置操作会添加诸如作者、许可证和说明的信息：

  1. services.AddSwaggerDocument(config =>
  2. {
  3.     config.PostProcess = document =>
  4.     {
  5.         document.Info.Version = "v1";
  6.         document.Info.Title = "ToDo API";
  7.         document.Info.Description = "A simple ASP.NET Core web API";
  8.         document.Info.TermsOfService = "None";
  9.         document.Info.Contact = new NSwag.OpenApiContact
  10.         {
  11.             Name = "Shayne Boyer",
  12.             Email = string.Empty,
  13.             Url = "https://twitter.com/spboyer"
  14.         };
  15.         document.Info.License = new NSwag.OpenApiLicense
  16.         {
  17.             Name = "Use under LICX",
  18.             Url = "https://example.com/license"
  19.         };
  20.     };
  21. });

Swagger UI 显示版本的信息：

带有版本信息的 Swagger UI

XML 注释XML comments

若要启用 XML 注释，请执行以下步骤：

  • 在“解决方案资源管理器”中右键单击该项目，然后选择“编辑 .csproj” 。
  • 手动将突出显示的行添加到 .csproj 文件 ：
  1. <PropertyGroup>
  2.   <GenerateDocumentationFile>true</GenerateDocumentationFile>
  3.   <NoWarn>$(NoWarn);1591</NoWarn>
  4. </PropertyGroup>
  • 右键单击“解决方案资源管理器” 中的项目，然后选择“属性”
  • 查看“生成”选项卡的“输出”部分下的“XML 文档文件”框
  • 在 Solution Pad 中，按 control 并单击项目名称 。导航到“工具” > “编辑文件” 。
  • 手动将突出显示的行添加到 .csproj 文件 ：
  1. <PropertyGroup>
  2.   <GenerateDocumentationFile>true</GenerateDocumentationFile>
  3.   <NoWarn>$(NoWarn);1591</NoWarn>
  4. </PropertyGroup>
  • 打开“项目选项”对话框 >“生成”>“编译器”
  • 查看“常规选项”部分下的“生成 xml 文档”框

手动将突出显示的行添加到 .csproj 文件 ：

  1. <PropertyGroup>
  2.   <GenerateDocumentationFile>true</GenerateDocumentationFile>
  3.   <NoWarn>$(NoWarn);1591</NoWarn>
  4. </PropertyGroup>
  1. <PropertyGroup>
  2.   <DocumentationFile>bin\$(Configuration)\$(TargetFramework)\$(AssemblyName).xml</DocumentationFile>
  3.   <NoWarn>$(NoWarn);1591</NoWarn>
  4. </PropertyGroup>

数据注释Data annotations

由于 NSwag 使用反射，且建议的 Web API 操作返回类型为 IActionResult，因此无法推断正在执行的操作和返回的内容。

请看下面的示例：

  1. [HttpPost]
  2. public IActionResult Create([FromBody] TodoItem item)
  3. {
  4.     if (item == null)
  5.     {
  6.         return BadRequest();
  7.     }
  9.     _context.TodoItems.Add(item);
  10.     _context.SaveChanges();
  12.     return CreatedAtRoute("GetTodo", new { id = item.Id }, item);
  13. }

上述操作返回 IActionResult，但在操作内部返回 CreatedAtRoute 或 BadRequest。使用数据注释告知客户端，已知此操作会返回哪些 HTTP 状态代码。使用以下属性标记该操作：

  1. [ProducesResponseType(typeof(TodoItem), StatusCodes.Status201Created)]  // Created
  2. [ProducesResponseType(StatusCodes.Status400BadRequest)]                 // BadRequest

由于 NSwag 使用反射，且建议的 Web API 操作返回类型为 ActionResult<T>，因此只能推断 T 定义的返回类型。无法自动推断其他可能的返回类型。

请看下面的示例：

  1. [HttpPost]
  2. public ActionResult<TodoItem> Create(TodoItem item)
  3. {
  4.     _context.TodoItems.Add(item);
  5.     _context.SaveChanges();
  7.     return CreatedAtRoute("GetTodo", new { id = item.Id }, item);
  8. }

上述操作将返回 ActionResult<T>。在操作中，它将返回 CreatedAtRoute。由于控制器具有 [ApiController] 属性，所以也可能出现 BadRequest 响应。有关详细信息，请参阅自动 HTTP 400 响应。使用数据注释告知客户端，已知此操作会返回哪些 HTTP 状态代码。使用以下属性标记该操作：

  1. [ProducesResponseType(StatusCodes.Status201Created)]     // Created
  2. [ProducesResponseType(StatusCodes.Status400BadRequest)]  // BadRequest

在 ASP.NET Core 2.2 或更高版本中，可使用约定，而不是使用 [ProducesResponseType] 显式修饰各操作。有关详细信息，请参阅 使用 Web API 约定。

Swagger 生成器现在可准确地描述此操作，且生成的客户端知道调用终结点时收到的内容。建议使用这些属性来标记所有操作。

有关 API 操作应返回的 HTTP 响应的指导原则，请参阅 RFC 7231 规范。