NSwag与ASP.NET Web API集成：传统项目升级指南-优快云博客

NSwag与ASP.NET Web API集成：传统项目升级指南

【免费下载链接】NSwag RicoSuter/NSwag: 是一个基于 .NET 平台的 OpenAPI 描述和代码生成工具，支持多种编程语言和框架。该项目提供了一个简单易用的 API，可以方便地实现 OpenAPI 描述和代码生成，同时支持多种编程语言和框架。项目地址: https://gitcode.com/gh_mirrors/ns/NSwag

为什么需要升级传统Web API项目？

传统ASP.NET Web API项目往往面临文档缺失、客户端集成复杂、接口变更管理困难等问题。NSwag作为OpenAPI工具链，能帮助团队自动生成API文档和客户端代码，减少人工维护成本。本文将以实际项目结构为基础，分步骤实现NSwag与传统Web API的集成。

项目准备与依赖安装

1. 确认项目结构

传统Web API项目集成NSwag需关注以下核心模块：

Web API核心包：NSwag.AspNet.WebApi
异常处理：JsonExceptionFilterAttribute
文档生成：NSwag.Generation.WebApi

2. 安装NuGet包

通过Package Manager控制台安装必要依赖：

Install-Package NSwag.AspNet.WebApi
Install-Package NSwag.Generation.WebApi

集成步骤

步骤1：配置异常处理过滤器

NSwag提供的JsonExceptionFilterAttribute可统一异常格式，在Global.asax.cs中注册：

public class WebApiApplication : System.Web.HttpApplication
{
    protected void Application_Start()
    {
        GlobalConfiguration.Configure(WebApiConfig.Register);
        // 注册NSwag异常过滤器
        GlobalConfiguration.Configuration.Filters.Add(
            new JsonExceptionFilterAttribute(hideStackTrace: true)
        );
    }
}

该过滤器位于src/NSwag.AspNet.WebApi/JsonExceptionFilterAttribute.cs，支持自定义异常类型和HTTP状态码映射。

步骤2：添加API文档生成配置

创建SwaggerConfig.cs配置文件，初始化OpenAPI文档生成器：

using NSwag.Generation.WebApi;
using NSwag;

public class SwaggerConfig
{
    public static void Register()
    {
        var document = new OpenApiDocument();
        var generator = new WebApiOpenApiDocumentGenerator(new WebApiOpenApiDocumentGeneratorSettings());
        
        var settings = new WebApiOpenApiDocumentGeneratorSettings
        {
            Title = "传统Web API升级示例",
            Description = "使用NSwag集成OpenAPI文档",
            Version = "v1"
        };
        
        var document = generator.GenerateForController<ValuesController>(settings);
        document.Save("openapi.json");
    }
}

步骤3：生成客户端代码

通过NSwag命令行工具生成TypeScript客户端：

nswag run nswag.json

典型的nswag.json配置示例可参考NSwag.Sample.NET80/nswag.json，包含文档路径、客户端类型和输出设置。

验证与测试

1. 查看生成的OpenAPI文档

集成完成后，可在项目根目录找到生成的openapi.json文件，包含所有API端点的详细描述。

2. 使用NSwagStudio验证

通过NSwagStudio可视化工具加载配置文件，验证文档生成结果：

高级配置

自定义API文档元数据

通过特性为控制器和方法添加描述：

using NSwag.Annotations;

[OpenApiTag("值操作", Description = "提供基本的数据操作接口")]
public class ValuesController : ApiController
{
    [SwaggerResponse(200, typeof(IEnumerable<string>), Description = "成功返回值列表")]
    public IEnumerable<string> Get()
    {
        return new string[] { "value1", "value2" };
    }
}

相关特性定义在NSwag.Annotations项目中。

集成Swagger UI

通过OWIN中间件托管Swagger UI（需安装NSwag.AspNet.Owin）：

public void Configuration(IAppBuilder app)
{
    app.UseSwaggerUi(typeof(WebApiApplication).Assembly, new SwaggerUiSettings
    {
        DocumentPath = "/openapi.json"
    });
}

工具链架构

NSwag通过分层架构实现文档生成与代码生成的解耦：

核心层：NSwag.Core提供OpenAPI文档模型
生成层：NSwag.Generation实现文档生成逻辑
集成层：NSwag.AspNet.WebApi提供Web API集成能力

总结与迁移建议

增量集成：先添加异常过滤器，再逐步配置文档生成
自动化：将客户端生成集成到MSBuild流程，参考NSwag.MSBuild
版本控制：对生成的openapi.json文件进行版本管理，跟踪API变更

完整项目示例可参考NSwag.Sample.NET80，包含了从配置到生成的全流程实现。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考