ASP.NET Core 中使用 NSwag 快速生成 API 文档与客户端代码

前言

在现代 Web 开发中，良好的 API 文档和高效的客户端代码生成是提升开发效率的关键。本文将介绍如何在 ASP.NET Core 项目中集成 NSwag 工具链，实现 API 文档自动生成、交互式测试界面以及客户端代码自动生成等功能。

NSwag 简介

NSwag 是一个强大的 .NET 工具集，主要提供三大核心功能：

1. Swagger/OpenAPI 规范生成：自动为 ASP.NET Core Web API 生成符合 OpenAPI 规范的文档
2. 交互式 UI：提供 Swagger UI 和 ReDoc 两种风格的 API 文档界面
3. 代码生成：根据 API 规范自动生成客户端代码（支持 C# 和 TypeScript）

环境准备

安装 NSwag 包

在 ASP.NET Core 项目中添加 NSwag.AspNetCore NuGet 包：

dotnet add package NSwag.AspNetCore

这个包包含了生成和提供 Swagger 规范、Swagger UI 以及 ReDoc UI 所需的所有中间件。

基础配置

1. 服务注册

在 Program.cs 中添加 OpenAPI 生成器服务：

builder.Services.AddOpenApiDocument(document =>
{
    document.Title = "Todo API";
    document.Description = "示例待办事项API";
    document.Version = "v1";
});

2. 中间件配置

启用中间件以提供生成的 OpenAPI 规范和 UI 界面：

if (app.Environment.IsDevelopment())
{
    // 提供OpenAPI规范
    app.UseOpenApi();
    
    // 提供Swagger UI
    app.UseSwaggerUi3(settings =>
    {
        settings.Path = "/swagger";
    });
    
    // 提供ReDoc UI
    app.UseReDoc(settings =>
    {
        settings.Path = "/redoc";
    });
}

启动应用后，可以通过以下 URL 访问：

• /swagger：Swagger UI 界面
• /swagger/v1/swagger.json：OpenAPI 规范文档
• /redoc：ReDoc 文档界面

代码生成实践

NSwag 提供了多种代码生成方式，下面介绍最常用的 NSwagStudio 方法：

使用 NSwagStudio 生成客户端代码

1. 下载并安装 NSwagStudio（Windows 桌面应用）
2. 启动后，在 "Swagger Specification URL" 输入 API 的 OpenAPI 规范地址
3. 点击 "Create local Copy" 生成规范副本
4. 在 "Outputs" 区域选择 "CSharp Client"
5. 点击 "Generate Outputs" 生成客户端代码

生成的客户端代码示例：

public partial class TodoClient 
{
    public async Task<ICollection<TodoItem>> GetAllAsync()
    {
        // 自动生成的调用逻辑
    }
    
    public async Task<TodoItem> CreateAsync(TodoItem item)
    {
        // 自动生成的调用逻辑
    }
}

客户端使用示例

var client = new TodoClient("http://localhost:5000");
var todos = await client.GetAllAsync();
var newItem = await client.CreateAsync(new TodoItem { Name = "学习NSwag" });

增强 API 文档

1. 添加 XML 注释

在项目文件中启用 XML 文档生成：

<PropertyGroup>
  <GenerateDocumentationFile>true</GenerateDocumentationFile>
</PropertyGroup>

然后在控制器方法上添加注释：

/// <summary>
/// 获取所有待办事项
/// </summary>
/// <returns>待办事项列表</returns>
[HttpGet]
public IEnumerable<TodoItem> GetAll()
{
    // ...
}

2. 使用数据注解

通过数据注解增强模型文档：

public class TodoItem
{
    [Required]
    [StringLength(100)]
    public string Name { get; set; }
    
    public bool IsComplete { get; set; }
}

3. 明确响应类型

使用 ProducesResponseType 标注预期的响应类型：

[HttpPost]
[ProducesResponseType(StatusCodes.Status201Created)]
[ProducesResponseType(StatusCodes.Status400BadRequest)]
public ActionResult<TodoItem> Create(TodoItem item)
{
    if (item == null)
    {
        return BadRequest();
    }
    
    // 创建逻辑
    return CreatedAtAction(nameof(Get), new { id = item.Id }, item);
}

高级配置

自定义 UI 样式

app.UseSwaggerUi3(settings =>
{
    settings.Path = "/api";
    settings.DocumentPath = "/api/specification.json";
    settings.CustomStylesheetPath = "custom-swagger.css";
});

安全定义

添加 JWT 认证支持：

document.AddSecurity("Bearer", new OpenApiSecurityScheme
{
    Type = OpenApiSecuritySchemeType.Http,
    Scheme = "bearer",
    BearerFormat = "JWT",
    Description = "请输入JWT令牌"
});

最佳实践建议

1. 版本控制：为不同 API 版本生成独立的文档
2. 示例数据：为模型属性提供示例值
3. 错误响应：统一定义错误响应模型
4. 生产环境：限制文档只在开发环境可用
5. 持续集成：将客户端代码生成加入构建流程

结语

通过 NSwag，我们可以轻松实现 ASP.NET Core Web API 的文档自动化和客户端代码生成，大幅提升前后端协作效率。本文介绍的基础配置和进阶技巧应该能够满足大多数项目的需求，开发者可以根据实际情况进行调整和扩展。