NSwag - 支持 .NET、ASP.NET Core 和 TypeScript 的 Swagger/OpenAPI 工具链

NSwag 项目介绍

NSwag 是一个用于 .NET、ASP.NET Core 和 TypeScript 的 Swagger/OpenAPI 工具链。它通过使用 JSON 和 JSON Schema 来描述 RESTful web API 来提供开放的 API 规范。NSwag 项目为 ASP.NET Web API 控制器生成 OpenAPI 规范，并从这些规范生成客户端代码。这个项目由 Rico Suter 和其他贡献者开发和维护。

项目特点

生成 OpenAPI 规格：NSwag 可以从 C# ASP.NET 控制器生成 Swagger 2.0 和 OpenAPI 3.0 规范，并且可以通过 ASP.NET 中间件服务这些规格，可以选择包含 Swagger UI 或 ReDoc。
客户端生成：从 OpenAPI 规格生成 C# 或 TypeScript 客户端或代理。这些操作可以通过命令行界面（CLI）自动化，并且可以通过 NuGet 工具或 NPM 分发。
友好的用户界面：NSwag 提供了一个简单易用的 Windows GUI 工具 NSwagStudio，用于生成和测试 API。

使用方式

NSwagStudio：提供一个简单易用的 Windows 图形界面。
中间件：通过 OpenAPI 或 Swagger UI 的 OWIN 和 ASP.NET Core 中间件使用。
命令行接口 (CLI)：支持 Windows、Mac 和 Linux。
C# 集成：可以通过 NuGet 包在 C# 代码中使用。
MSBuild 集成：可以在 .csproj 文件中使用 ServiceProjectReference 标签。

教程

NSwag 提供了一些教程，帮助开发者更好地集成该工具链：

如何在 ASP.NET Core 应用中添加 NSwag。
将 NSwag 工具链集成到 ASP.NET Web API 项目中。
从现有的 ASP.NET Web API Web 程序集中生成 Angular TypeScript 客户端。

代码生成器

CSharp Client：生成 C# 客户端代码，支持 .NET Framework、.NET Core、Xamarin 和 .NET Standard。
CSharp Controllers：生成基于 OpenAPI 规格的 Web API 控制器。
TypeScript Client：从 OpenAPI 规格生成 TypeScript 客户端，支持多种框架模板，如 JQuery、Angular、Aurelia 等。

下载和包管理

用户可以从 GitHub 下载最新的 NSwagStudio 和命令行工具。同时，NSwag 也可以作为 NPM 包进行分发。此外，NSwag 还有不同功能的 NuGet 包，支持各种 .NET 平台和功能。

在 C# 中的使用

在 ASP.NET Core 项目中，可以通过在 Startup.cs 文件中注册来生成 OpenAPI 规格并渲染 UI。以下是使用中间件的基本示例：

public class Startup
{
    public void ConfigureServices(IServiceCollection services)
    {
        services.AddOpenApiDocument();
    }

    public void Configure(IApplicationBuilder app, IHostingEnvironment env, ILoggerFactory loggerFactory)
    {
        app.UseOpenApi();
        app.UseSwaggerUi();
        app.UseReDoc();
    }
}

最后，NSwag 的工具和功能不仅适用于 .NET 开发者，还为 TypeScript 开发者提供了一套集成的解决方案，让他们可以更好地利用 OpenAPI/Swagger 规格来简化 API 开发和使用流程。