NSwag CLI全攻略：Windows、Mac与Linux跨平台命令行使用指南-优快云博客

NSwag CLI全攻略：Windows、Mac与Linux跨平台命令行使用指南

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

你还在为不同操作系统间API文档和客户端代码生成工具的兼容性问题烦恼吗？还在寻找一种能在Windows、Mac和Linux上统一使用的OpenAPI工具链吗？本文将全面介绍NSwag CLI（命令行界面）的安装、配置和使用方法，让你在任何操作系统上都能轻松生成高质量的API文档和客户端代码。读完本文，你将能够：掌握NSwag CLI的跨平台安装方法，熟练使用核心命令生成OpenAPI规范和客户端代码，了解配置文件的使用技巧，以及解决常见问题。

NSwag CLI简介

NSwag是一个基于.NET平台的OpenAPI描述和代码生成工具，它将Swashbuckle（OpenAPI/Swagger生成）和AutoRest（客户端生成）的功能整合到一个工具链中，避免了许多兼容性问题，并提供了对JSON Schema更完善的支持，如继承、枚举和引用处理等。NSwag CLI是NSwag项目的命令行接口，允许开发者通过命令行轻松生成OpenAPI规范和客户端代码，支持Windows、Mac和Linux等多种操作系统。

NSwag CLI的核心功能包括：从C# ASP.NET (Core)控制器生成Swagger 2.0和OpenAPI 3.0规范，通过ASP.NET (Core)中间件提供规范服务（可选Swagger UI或ReDoc），从规范生成C#或TypeScript客户端/代理，以及通过CLI实现自动化（通过NuGet工具、构建目标或NPM分发）。

NSwag工具链的架构如图所示，它展示了NSwag如何从不同的输入（如Web API程序集、OpenAPI规范）生成各种输出（如客户端代码、控制器代码）。更多项目信息可参考README.md。

跨平台安装指南

Windows系统安装

在Windows系统上，有多种安装NSwag CLI的方式，你可以根据自己的需求选择最适合的方式。

通过NuGet安装

如果你使用Visual Studio或.NET SDK，可以通过NuGet安装NSwag CLI。在项目文件中添加以下包引用：

<DotNetCliToolReference Include="NSwag.ConsoleCore" Version="14.2.0" />

然后在命令行中运行dotnet restore安装依赖。安装完成后，可以使用dotnet nswag命令调用NSwag CLI。

通过NPM安装

如果你已经安装了Node.js和npm，可以通过npm安装NSwag CLI。打开命令提示符或PowerShell，运行以下命令：

npm install -g nswag

安装完成后，可以直接使用nswag命令调用NSwag CLI。NSwag的npm包信息可参考src/NSwag.Npm/package.json。

Mac与Linux系统安装

在Mac和Linux系统上，主要通过.NET SDK或npm来安装NSwag CLI。

通过.NET SDK安装

首先确保已安装.NET SDK（.NET Core 3.1或更高版本）。然后在终端中运行以下命令安装NSwag CLI：

dotnet tool install -g NSwag.ConsoleCore

安装完成后，你可能需要将工具路径添加到系统环境变量中。对于bash或zsh，可将以下内容添加到.bashrc或.zshrc文件中：

export PATH="$PATH:$HOME/.dotnet/tools"

之后，你可以使用nswag命令调用NSwag CLI。

通过NPM安装

与Windows系统类似，如果你已安装Node.js和npm，可以通过npm在Mac或Linux上安装NSwag CLI：

npm install -g nswag

安装完成后，直接使用nswag命令即可。

安装完成后，你可以通过运行nswag version命令来验证安装是否成功。如果安装成功，命令行会显示NSwag CLI的版本信息，如：

NSwag command line tool for .NET Core 3.1.0, 14.2.0.0

核心命令详解

NSwag CLI提供了丰富的命令来满足不同的需求，以下是一些常用的核心命令及其用法。

生成OpenAPI规范

从Web API项目生成

如果你有一个ASP.NET Core Web API项目，可以使用aspnetcore2openapi命令生成OpenAPI规范。例如，对于一个名为MyWebApi.csproj的项目，你可以运行：

nswag aspnetcore2openapi /project:MyWebApi.csproj /output:openapi.json

这个命令会分析指定的项目，生成OpenAPI规范文件openapi.json。命令的参数还包括/documentName（文档名称）、/configuration（构建配置）、/runtime（运行时）等，可根据需要进行调整。

从类型生成

如果你想从指定的.NET类型生成OpenAPI规范，可以使用types2openapi命令。例如：

nswag types2openapi /assembly:MyAssembly.dll /output:openapi.json

这个命令会分析MyAssembly.dll中的类型，生成包含这些类型的OpenAPI规范文件。

生成客户端代码

生成C#客户端

使用openapi2csclient命令可以从OpenAPI规范生成C#客户端代码。例如：

nswag openapi2csclient /input:openapi.json /output:Client.cs /className:MyApiClient /namespace:MyNamespace

这个命令会根据openapi.json生成C#客户端代码文件Client.cs，客户端类名为MyApiClient，命名空间为MyNamespace。

openapi2csclient命令有许多可配置的参数，如/ClientBaseClass（客户端基类）、/GenerateClientInterfaces（是否生成客户端接口）、/InjectHttpClient（是否注入HttpClient）等。详细的参数说明可参考src/NSwag.Commands/Commands/CodeGeneration/OpenApiToCSharpClientCommand.cs。

生成TypeScript客户端

使用openapi2tsclient命令可以从OpenAPI规范生成TypeScript客户端代码。例如：

nswag openapi2tsclient /input:openapi.json /output:client.ts /className:MyApiClient /template:Fetch

这个命令会根据openapi.json生成TypeScript客户端代码文件client.ts，客户端类名为MyApiClient，使用Fetch模板。

openapi2tsclient命令的参数包括/ClassName（类名）、/ModuleName（模块名）、/Template（模板类型，如JQueryCallbacks、JQueryPromises、Angular、Fetch等）等。详细的参数说明可参考src/NSwag.Commands/Commands/CodeGeneration/OpenApiToTypeScriptClientCommand.cs。

常用命令速查表

命令	描述	示例
`nswag version`	显示NSwag CLI版本信息	`nswag version`
`nswag aspnetcore2openapi`	从ASP.NET Core项目生成OpenAPI规范	`nswag aspnetcore2openapi /project:MyProject.csproj /output:openapi.json`
`nswag openapi2csclient`	从OpenAPI规范生成C#客户端	`nswag openapi2csclient /input:openapi.json /output:Client.cs`
`nswag openapi2tsclient`	从OpenAPI规范生成TypeScript客户端	`nswag openapi2tsclient /input:openapi.json /output:client.ts`
`nswag run`	运行nswag.json配置文件	`nswag run myconfig.nswag.json`

配置文件详解

NSwag CLI支持使用配置文件来定义生成过程，这对于复杂的生成需求或需要重复使用的配置非常有用。配置文件通常使用JSON格式，以.nswag.json为扩展名。

配置文件结构

一个典型的NSwag配置文件包含runtime、documentGenerator和codeGenerators等部分。runtime指定运行时版本，documentGenerator配置文档生成器（如从ASP.NET Core项目生成OpenAPI规范），codeGenerators配置代码生成器（如生成C#客户端、TypeScript客户端、C#控制器等）。

以下是一个示例配置文件src/NSwag.Sample.NET80Minimal/nswag.json的简化版本：

{
  "runtime": "Net80",
  "documentGenerator": {
    "aspNetCoreToOpenApi": {
      "project": "NSwag.Sample.NET80Minimal.csproj",
      "output": "openapi.json"
    }
  },
  "codeGenerators": {
    "openApiToTypeScriptClient": {
      "className": "{controller}Client",
      "template": "Fetch",
      "output": "GeneratedClientsTs.gen"
    },
    "openApiToCSharpClient": {
      "className": "{controller}Client",
      "namespace": "MyNamespace",
      "output": "GeneratedClientsCs.gen"
    }
  }
}

在这个配置文件中，documentGenerator部分配置了从ASP.NET Core项目生成OpenAPI规范，codeGenerators部分配置了生成TypeScript客户端和C#客户端。

使用配置文件生成代码

要使用配置文件运行NSwag CLI，只需在命令行中执行：

nswag run myconfig.nswag.json

NSwag CLI会读取配置文件中的设置，依次执行文档生成和代码生成任务。

自定义配置示例

你可以根据自己的需求自定义配置文件。例如，如果你想生成一个使用Angular模板的TypeScript客户端，并指定命名空间和类名，可以这样配置：

"openApiToTypeScriptClient": {
  "className": "ApiClient",
  "moduleName": "my-api",
  "namespace": "MyApp.Api",
  "template": "Angular",
  "rxJsVersion": 7.0,
  "output": "src/app/api/api-client.ts"
}

这个配置会生成一个名为ApiClient的Angular客户端，模块名为my-api，命名空间为MyApp.Api，使用RxJs 7.0，并将输出文件保存到src/app/api/api-client.ts。

实战案例：生成TypeScript客户端

准备工作

在开始之前，确保你已经安装了NSwag CLI，并拥有一个OpenAPI规范文件（如openapi.json）。如果没有，你可以使用NSwag从现有的ASP.NET Core项目生成，例如：

nswag aspnetcore2openapi /project:MyWebApi.csproj /output:openapi.json

生成命令与参数说明

假设我们有一个openapi.json文件，想要生成一个使用Fetch模板的TypeScript客户端，类名为UserClient，输出到src/services/user-client.ts。可以使用以下命令：

nswag openapi2tsclient /input:openapi.json /output:src/services/user-client.ts /className:UserClient /template:Fetch /generateClientInterfaces:true

这个命令中，/input指定输入的OpenAPI规范文件，/output指定输出的TypeScript文件路径，/className指定客户端类名，/template指定使用Fetch模板，/generateClientInterfaces设置为true表示生成客户端接口。

生成结果与代码解析

生成的TypeScript客户端代码会包含与OpenAPI规范中定义的API操作对应的方法。例如，如果OpenAPI规范中有一个GET /api/users的操作，生成的客户端会有一个getUsers()方法。

以下是生成的代码示例（简化版）：

export interface User {
  id: number;
  name: string;
  email: string;
}

export interface UserClient {
  getUsers(): Promise<User[]>;
  getUserById(id: number): Promise<User>;
  createUser(user: User): Promise<User>;
  updateUser(id: number, user: User): Promise<User>;
  deleteUser(id: number): Promise<void>;
}

export class UserClient implements UserClient {
  private baseUrl: string;

  constructor(baseUrl?: string) {
    this.baseUrl = baseUrl || "";
  }

  async getUsers(): Promise<User[]> {
    const url = new URL(this.baseUrl + "/api/users");
    const response = await fetch(url.toString(), { method: "GET" });
    if (!response.ok) {
      throw new ApiException(response.status, await response.text());
    }
    return await response.json() as User[];
  }

  // 其他方法实现...
}

生成的代码定义了User接口表示用户数据，UserClient接口定义客户端方法，UserClient类实现了这些方法。每个方法使用Fetch API发送HTTP请求，并处理响应和错误。

常见问题与解决方案

跨平台兼容性问题

问题描述：在Mac或Linux系统上运行nswag命令时，提示“命令未找到”。

解决方案：这通常是因为NSwag CLI的安装路径没有添加到系统环境变量中。如果你通过.NET SDK安装，确保$HOME/.dotnet/tools在PATH环境变量中。可以通过echo $PATH检查，如果没有，可将以下内容添加到.bashrc或.zshrc文件中：

export PATH="$PATH:$HOME/.dotnet/tools"

然后运行source ~/.bashrc或source ~/.zshrc使更改生效。

生成的客户端代码有误

问题描述：生成的客户端代码中存在语法错误或不符合预期的代码。

解决方案：首先检查OpenAPI规范文件是否正确，可以使用Swagger UI等工具验证。如果规范文件正确，可能是代码生成器的配置参数不正确。尝试调整相关参数，如/template、/namespace、/className等。如果问题仍然存在，可以查看NSwag的GitHub仓库中的 issues 或提交新的 issue 寻求帮助。

中文乱码问题

问题描述：在Windows系统的命令提示符中，NSwag CLI的输出出现中文乱码。

解决方案：这是由于命令提示符的字符编码与NSwag CLI的输出编码不匹配导致的。可以尝试将命令提示符的字符编码设置为UTF-8：

chcp 65001

然后再运行NSwag CLI命令。

总结与展望

NSwag CLI是一个功能强大的跨平台OpenAPI工具链，它为开发者提供了从API设计到客户端代码生成的一站式解决方案。通过本文的介绍，你已经了解了NSwag CLI的安装方法、核心命令、配置文件使用和实战案例。

NSwag项目一直在积极开发和维护中，未来可能会添加更多新功能和改进，如对最新OpenAPI规范的支持、更多代码生成模板、更好的IDE集成等。你可以通过关注项目的GitHub仓库来获取最新动态。

希望本文能够帮助你更好地使用NSwag CLI，提高API开发效率。如果你有任何问题或建议，欢迎在项目的GitHub仓库中提出。

最后，如果你觉得本文对你有帮助，请点赞、收藏并关注，以便获取更多关于NSwag和API开发的教程和技巧。下期我们将介绍NSwag在ASP.NET Core项目中的高级应用，敬请期待！

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