NSwag 和 ASP.NET Core

NSwag 提供了下列功能：

• 能够使用 Swagger UI 和 Swagger 生成器。

• 灵活的代码生成功能。

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

注册 NSwag 中间件

注册 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 文件的目录

  • 请执行以下命令：

    Install-Package NSwag.AspNetCore
    

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

  • 右键单击“解决方案资源管理器” > “管理 NuGet 包”中的项目

  • 将“包源”设置为“nuget.org”

  • 在搜索框中输入“NSwag.AspNetCore”

  • 从“浏览”选项卡中选择“NSwag.AspNetCore”包，然后单击“安装”

添加并配置 Swagger 中间件

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

• 导入下列命名空间：

using NJsonSchema;
using NSwag.AspNetCore;

• 在 ConfigureServices 方法中，注册所需的 Swagger 服务：

public void ConfigureServices(IServiceCollection services)
{
    services.AddDbContext<TodoContext>(opt => 
        opt.UseInMemoryDatabase("TodoList"));
    services.AddMvc();

// Register the Swagger services
    services.AddSwaggerDocument();
}

• 在 Configure 方法中，启用中间件为生成的 Swagger 规范和 Swagger UI 提供服务：

public void Configure(IApplicationBuilder app)
{
    app.UseStaticFiles();

// Register the Swagger generator and the Swagger UI middlewares
    app.UseSwagger();
    app.UseSwaggerUi3();

    app.UseMvc();
}

• 启动应用。 转到：

  • http://localhost:<port>/swagger，以查看 Swagger UI。

  • http://localhost:<port>/swagger/v1/swagger.json，以查看 Swagger 规范。

代码生成

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

• NSwagStudio – 一款 Windows 桌面应用，用于以 C# 或 TypeScript 生成 API 客户端代码。

• NSwag.CodeGeneration.CSharp 或 NSwag.CodeGeneration.TypeScript NuGet 包 - 用于在项目中生成代码。

• 通过命令行使用 NSwag。

• NSwag.MSBuild NuGet 包。

使用 NSwagStudio 生成代码

• 按照 NSwagStudio GitHub 存储库中的说明操作，以安装 NSwagStudio。

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

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

  
  

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

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

//----------------------
// <auto-generated>
//     Generated using the NSwag toolchain v12.0.9.0 (NJsonSchema v9.13.10.0 (Newtonsoft.Json v11.0.0.0)) (http://NSwag.org)
// </auto-generated>
//----------------------

namespace MyNamespace
{
#pragma warning disable

    [System.CodeDom.Compiler.GeneratedCode("NSwag", "12.0.9.0 (NJsonSchema v9.13.10.0 (Newtonsoft.Json v11.0.0.0))")]
public partial class TodoClient
    {
private string _baseUrl = "https://localhost:44354";
private System.Net.Http.HttpClient _httpClient;
private System.Lazy<Newtonsoft.Json.JsonSerializerSettings> _settings;

public TodoClient(System.Net.Http.HttpClient httpClient)
{
            _httpClient = httpClient;
            _settings = new System.Lazy<Newtonsoft.Json.JsonSerializerSettings>(() =>
            {
var settings = new Newtonsoft.Json.JsonSerializerSettings();
                UpdateJsonSerializerSettings(settings);
return settings;
            });
        }

public string BaseUrl
        {
get { return _baseUrl; }
set { _baseUrl = value; }
        }

// code omitted for brevity

 提示

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

• 将生成的 C# 代码复制到使用 API 的客户端项目内的文件中。

• 开始使用 Web API：

 var todoClient = new TodoClient();

// Gets all to-dos from the API
var allTodos = await todoClient.GetAllAsync();

// Create a new TodoItem, and save it via the API.
var createdTodo = await todoClient.CreateAsync(new TodoItem());

// Get a single to-do by ID
var foundTodo = await todoClient.GetByIdAsync(1);

自定义 API 文档

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

API 信息和说明

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

services.AddSwaggerDocument(config =>
{
    config.PostProcess = document =>
    {
        document.Info.Version = "v1";
        document.Info.Title = "ToDo API";
        document.Info.Description = "A simple ASP.NET Core web API";
        document.Info.TermsOfService = "None";
        document.Info.Contact = new NSwag.SwaggerContact
        {
            Name = "Shayne Boyer",
            Email = string.Empty,
            Url = "https://twitter.com/spboyer"
        };
        document.Info.License = new NSwag.SwaggerLicense
        {
            Name = "Use under LICX",
            Url = "https://example.com/license"
        };
    };
});

Swagger UI 显示版本的信息：

XML 注释

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

• Visual Studio

• Visual Studio for Mac

• Visual Studio Code

• 在“解决方案资源管理器”中右键单击该项目，然后选择“编辑 <project_name>.csproj”。

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

<PropertyGroup>
  <GenerateDocumentationFile>true</GenerateDocumentationFile>
<NoWarn>$(NoWarn);1591</NoWarn>
</PropertyGroup>

数据注释

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

请看下面的示例：

[HttpPost]
public ActionResult<TodoItem> Create(TodoItem item)
{
    _context.TodoItems.Add(item);
    _context.SaveChanges();

return CreatedAtRoute("GetTodo", new { id = item.Id }, item);
}

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

[ProducesResponseType(201)]     // Created
[ProducesResponseType(400)]     // BadRequest

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

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

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

原文地址：https://docs.microsoft.com/zh-cn/aspnet/core/tutorials/getting-started-with-nswag

.NET社区新闻，深度好文，欢迎访问公众号文章汇总 http://www.csharpkit.com