NSwag与Postman：生成的OpenAPI规范直接导入Postman-postman-CSS教程网

NSwag与Postman：生成的OpenAPI规范直接导入Postman

【免费下载链接】NSwag 项目地址: https://gitcode.***/gh_mirrors/nsw/NSwag

你是否还在为API文档与测试工具之间的格式转换而烦恼？是否希望从.***项目直接生成可导入Postman的API规范？本文将展示如何使用NSwag自动生成OpenAPI规范并无缝集成到Postman，解决API开发中的文档与测试效率问题。读完本文你将掌握：NSwag生成OpenAPI的三种方法、规范文件结构解析、Postman导入全流程以及自动化工作流配置。

NSwag作为.***生态的OpenAPI工具链，核心价值在于将API规范生成与客户端代码生成整合为一体。其架构涵盖规范生成器、代码生成器和中间件三大组件，支持从ASP.*** Core控制器直接生成OpenAPI 3.0规范。

生成OpenAPI规范文件

使用ASP.*** Core中间件实时生成

在ASP.*** Core项目中配置NSwag中间件，可在开发过程中实时生成并提供OpenAPI规范。修改Program.cs添加以下代码：

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddOpenApiDocument(); // 注册OpenAPI文档生成器

var app = builder.Build();
app.UseOpenApi(); // 提供OpenAPI规范端点
app.UseSwaggerUi(); // 提供Swagger UI界面

启动应用后，通过/swagger/v1/swagger.json即可访问实时生成的规范文件。这种方式适合开发阶段快速调试，无需手动生成文件。

通过NSwagStudio可视化配置生成

NSwagStudio提供图形界面配置生成参数，适合不熟悉命令行的开发者。从NSwagStudio下载安装后，选择"ASP.*** Core"文档源，配置项目路径和输出文件：

配置完成后点击"Generate Outputs"，将在指定位置生成OpenAPI规范文件（如openapi.json）。

使用命令行工具生成

对于CI/CD流程或自动化场景，命令行工具更为适合。通过NuGet安装NSwag CLI后，执行以下命令：

nswag run src/NSwag.Sample.***80Minimal/nswag.json

上述命令将使用示例项目中的配置文件src/NSwag.Sample.***80Minimal/nswag.json生成规范。配置文件定义了项目路径、输出格式等关键参数：

{
  "documentGenerator": {
    "asp***CoreToOpenApi": {
      "project": "NSwag.Sample.***80Minimal.csproj",
      "output": "openapi.json"
    }
  }
}

OpenAPI规范文件结构解析

生成的OpenAPI规范文件包含API的完整描述，以src/NSwag.Sample.***80Minimal/openapi.json为例，主要结构如下：

{
  "openapi": "3.0.0",
  "info": { "title": "Minimal API", "version": "v1" },
  "paths": {
    "/sum/{a}/{b}": {
      "get": {
        "operationId": "CalculateSum",
        "parameters": [
          { "name": "a", "in": "path", "schema": { "type": "integer" } },
          { "name": "b", "in": "path", "schema": { "type": "integer" } }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": { "schema": { "type": "integer" } }
            }
          }
        }
      }
    }
  }
}

关键部分说明：

info: 包含API标题、版本等元数据
paths: 定义所有API端点及参数、响应信息
***ponents: 可复用的模式定义（如数据模型）

Postman通过解析这些结构自动创建集合、请求和参数，实现API测试的快速配置。

导入Postman的完整流程

导入步骤

打开Postman，点击左上角"Import"按钮
选择"File"选项卡，上传生成的openapi.json文件
在导入设置页面保持默认配置，点击"Import"完成导入

导入后自动生成的内容

成功导入后，Postman将自动创建：

包含所有API端点的集合
带有参数和请求体的示例请求
响应验证规则
环境变量模板

验证导入结果

导入完成后，可通过以下步骤验证：

在左侧导航栏选择新创建的集合
选择任意端点（如GET /sum/{a}/{b}）
填写参数值并发送请求
检查响应是否符合预期

Postman会根据OpenAPI规范自动设置请求头、参数格式等，大幅减少手动配置工作。

高级应用：自动化工作流配置

配置NSwag自动更新规范文件

在项目文件中添加MSBuild目标，实现构建时自动更新规范：

<Target Name="GenerateOpenApiSpec" AfterTargets="Build">
  <Exec ***mand="nswag run nswag.json" />
</Target>

集成Postman Newman进行自动化测试

结合Postman的命令行工具Newman，可将API测试集成到CI流程：

newman run MyApiCollection.json -e production-environment.json

其中MyApiCollection.json可通过Postman导出，或直接从OpenAPI规范生成：

newman run openapi.json -r cli,json

常见问题解决

导入时出现格式错误

原因：NSwag生成的规范可能包含Postman不支持的高级特性。
解决：在NSwag配置中禁用这些特性：

"documentGenerator": {
  "asp***CoreToOpenApi": {
    "serializerSettings": {
      "ignoreUnsupportedTypes": true
    }
  }
}

参数类型不匹配

原因：.***类型与OpenAPI类型映射存在差异。
解决：使用NSwag注解显式指定类型：

[OpenApiParameter(Description = "用户ID", Type = typeof(int))]
public IActionResult GetUser(int id)

导入后缺少认证信息

解决：在OpenAPI规范中添加安全定义，NSwag支持通过注解配置：

[OpenApiSecurity("Bearer", SecuritySchemeType.Http, Scheme = "bearer")]
public class MyController : ControllerBase

总结与最佳实践

本文介绍了使用NSwag生成OpenAPI规范并导入Postman的完整流程，涵盖中间件、GUI和命令行三种生成方式，以及规范文件的结构解析和导入验证。关键最佳实践包括：

开发阶段使用中间件实时生成，便于调试
提交代码前通过NSwagStudio验证规范完整性
CI/CD流程集成命令行工具实现自动生成
导入Postman后创建环境变量集合，适配不同部署环境
定期同步规范文件与Postman集合，确保测试准确性

通过NSwag与Postman的无缝集成，可显著提升API开发效率，减少文档与测试的维护成本。完整示例可参考NSwag.Sample.***80Minimal项目，包含规范生成和客户端代码生成的完整配置。