NSwag教程：使用CLI工具生成服务代理客户端代码

鲁通彭Mercy

于 2025-06-06 09:04:14 发布

阅读量276

点赞数 4

CC 4.0 BY-SA版权

本文链接：https://blog.youkuaiyun.com/gitblog_00816/article/details/148464880

NSwag教程：使用CLI工具生成服务代理客户端代码

NSwag 项目地址: https://gitcode.com/gh_mirrors/nsw/NSwag

前言

在现代分布式系统开发中，客户端应用经常需要与第三方服务进行交互。NSwag作为.NET生态中强大的Swagger/OpenAPI工具链，能够帮助我们快速生成强类型的客户端代理代码，显著提升开发效率。本文将详细介绍如何使用NSwag CLI工具生成服务客户端代理代码。

场景假设

假设你加入了一个大型项目团队，需要开发一个客户端应用（可能是移动端、桌面端或Web应用），该应用需要集成一个第三方服务。这个第三方服务提供了完整的OpenAPI规范文档，但你对服务内部实现没有深入了解和修改权限。

准备工作

环境要求

NSwag CLI工具：这是生成客户端代码的核心工具
Visual Studio Code（可选）：推荐安装OpenAPI/Swagger编辑器扩展，便于查看和验证API文档
.NET 5.0+运行时：确保你的开发环境已安装

注意事项

如果使用ZIP方式安装NSwag遇到问题，建议使用Chocolatey或MSI安装包
执行命令时可能需要指定运行时版本，如：nswag version /runtime:Net50
本文示例使用公开的Swagger Petstore API作为演示

生成客户端代码的两种方式

方式一：使用现有配置快速生成

准备NSwag配置文件：使用类似[sample.nswag]的配置文件
创建项目目录结构：
- MainApp/Services/[YourRemoteService]：存放服务客户端代码
- MainApp/Contracts/[YourRemoteService]：存放接口和DTO定义
获取API文档：
- 如果服务提供公开的OpenAPI端点，可直接使用
- 否则下载API文档到本地
执行生成命令：
```
nswag run sample.nswag /runtime:Net50
```
整合生成代码：将输出文件放入对应目录
更新依赖注入配置：检查是否需要更新服务注册

方式二：自定义配置生成

创建自定义配置文件：基于以下模板修改
关键配置项说明：
- documentGenerator.fromDocument.url：指定OpenAPI文档位置（URL或本地路径）
- codeGenerators.openApiToCSharpClient.className：设置生成的服务类名
- codeGenerators.openApiToCSharpClient.namespace：设置命名空间
- generateContractsOutput：设为true可分离接口和DTO定义
执行生成命令：
```
nswag run custom.nswag /runtime:Net50
```
整合生成代码：同上

NSwag配置详解

以下是一个完整的配置示例，包含主要参数的说明：

{
    "runtime": "Net50",
    "documentGenerator": {
        "fromDocument": {
            "url": "YOUR_OPENAPI_SPEC_LOCATION_HERE"
        }
    },    
    "codeGenerators": {
        "openApiToCSharpClient": {
            "generateClientClasses": true,
            "generateClientInterfaces": true,
            "generateDtoTypes": true,
            "injectHttpClient": true,
            "clientBaseClass": "MainApp.Services.BaseService",
            "generateContractsOutput": true,
            "contractsNamespace": "MainApp.Services.SampleService.Contracts",
            "className": "SampleService",
            "namespace": "MainApp.Services.SampleService",
            "operationGenerationMode": "MultipleClientsFromOperationId",
            "generateSyncMethods": false,
            "generateResponseClasses": true
        }
    }
}

关键参数说明

代码生成选项：
- generateClientClasses：是否生成客户端类
- generateClientInterfaces：是否生成客户端接口
- generateDtoTypes：是否生成DTO类型
HTTP客户端配置：
- injectHttpClient：是否注入HttpClient
- disposeHttpClient：是否自动释放HttpClient
命名空间与类名：
- namespace：设置主命名空间
- contractsNamespace：设置合约命名空间
- className：设置生成的主类名
操作模式：
- operationGenerationMode：操作方法生成模式
- generateSyncMethods：是否生成同步方法