使用 swagger-codegen 生成的 Dart 客户端Petstore 测试套件的运行与原理详解【免费下载链接】swagger-codegenswagger-codegen contains a template-driven engine to generate documentation, API clients and server stubs in different languages by parsing your OpenAPI / Swagger definition.项目地址: https://gitcode.com/gh_mirrors/sw/swagger-codegen导读本指南以 swagger-codegen 仓库中的 Dart Petstore 客户端测试示例 为核心完整讲解如何运行基于 OpenAPI/Swagger 定义自动生成的 Dart API 客户端测试包括浏览器pub servetests.html与 Dart VM 两种运行方式、期望的测试输出以及底层客户端库ApiClient的调用链与认证机制。读完本文你将能独立复现这套测试流程并理解 swagger-codegen 生成 Dart 客户端时测试代码、库代码与依赖配置之间的关系。测试示例在仓库中的位置与构成该示例位于 samples/client/petstore/dart/petstore是 swagger-codegen 依据 Petstore 规范为 Dart 语言生成的完整测试工程。整个示例由两部分组成petstore 测试工程即本指南的核心目录包含测试入口 test/tests.dart、浏览器宿主页 test/tests.html、针对 Pet/Store/User 三组 API 的测试文件以及工程声明 pubspec.yaml。swagger 客户端库通过pubspec.yaml中的swagger: path: ../swagger-browser-client以本地路径方式依赖即 swagger-browser-client其中包含ApiClient、认证模块、模型类与各 API 实现。工程依赖声明如下pubspec.yamlname: petstore_client version: 1.0.0 description: Petstore client using swagger API library dependencies: swagger: path: ../swagger-browser-client browser: any dev_dependencies: guinness: ^0.1.17其中guinness是测试框架提供describe/it/expect等 BDD 风格断言browser用于浏览器环境而客户端库本身则依赖http: 0.11.1 0.12.0见 swagger-browser-client/pubspec.yaml。方式一在浏览器中运行测试原文档给出的最快验证路径是浏览器方式全程两条命令即可启动 Dart 开发服务器pub serve在浏览器中打开测试宿主页http://127.0.0.1:8080/tests.html打开页面即自动开始执行测试。注意页面本身不会显示任何通过/失败提示——你需要打开浏览器的 JavaScript / Dart 控制台DevTools Console来观察测试进度与结果。原文档明确提示there isNOfeedback!这是这套浏览器测试方案的显著特点一切断言输出都通过print/unittest-suite-*约定写入控制台。tests.html 的宿主逻辑非常简单通过script typeapplication/dart srctests.dart加载测试脚本再由script srcpackages/browser/dart.js完成 Dart 到 JS 的编译与引导。期望的浏览器控制台输出原文档给出了完整的预期输出是判断测试是否全部通过的唯一依据完整继承如下Observatory listening at http://127.0.0.1:39067/ unittest-suite-wait-for-done GET http://petstore.swagger.io/v2/pet/957639 404 (Not Found) GET http://petstore.swagger.io/v2/pet/525946 404 (Not Found) GET http://petstore.swagger.io/v2/store/order/29756 404 (Not Found) GET http://petstore.swagger.io/v2/user/Riddlem325 404 (Not Found) PASS: Pet API adds a new pet and gets it by id PASS: Pet API doesnt get non-existing pet by id PASS: Pet API deletes existing pet by id PASS: Pet API updates pet with form PASS: Pet API updates existing pet PASS: Pet API finds pets by status PASS: Pet API finds pets by tag PASS: Pet API uploads a pet image PASS: Store API places an order and gets it by id PASS: Store API deletes an order PASS: Store API gets the store inventory PASS: User API creates a user PASS: User API creates users with list input PASS: User API updates a user PASS: User API deletes a user PASS: User API logs a user in All 16 tests passed. unittest-suite-success需要注意几点解读输出中穿插的 4 条404 (Not Found)是预期行为来自测试中查询不存在对象并期望抛出ApiException的负向用例详见下文测试源码解析并非测试失败unittest-suite-wait-for-done表示测试套件已就绪并等待异步用例完成最后的All 16 tests passed.与unittest-suite-success才是全部通过的确证。方式二在 Dart VM 中运行测试若不想依赖浏览器环境可以改为在 Dart VM命令行中直接执行测试。原文档提供了两条并列的切换路径任选其一即可。切换方案 A使用生成脚本README 提及原文档描述为修改bin/dart-petstore.sh取消注释其中的 vm 选项行运行bin/dart-petstore.sh。需要说明的是当前仓库快照的samples/client/petstore/dart/petstore目录下并未包含该脚本仅见 test、README.md 与 pubspec.yaml因此此方案适用于完整生成的工程副本实际使用时请以你本地生成结果中的脚本内容为准。切换方案 B直接修改客户端库代码仓库可验证这是当前仓库内可完整验证的方式共两步在 swagger-browser-client/lib/api_client.dart 中将默认 HTTP 客户端从浏览器实现切换为纯 Dart VM 实现// 原来浏览器环境 var client new BrowserClient(); // 改为VM 环境 var client new Client();在 swagger-browser-client/lib/api.dart 中删除对浏览器客户端的导入import package:http/browser_client.dart;完成切换后运行dart test/tests.dart即可在 VM 中直接执行全部测试。其原理在于BrowserClient依赖浏览器的XMLHttpRequest能力只能运行于 dart2js 编译后的浏览器环境而package:http的Client()基于dart:io的HttpClient可在命令行 VM 中直连远端 API。测试入口与用例源码解析入口tests.dart 的组织方式test/tests.dart 是全部测试的唯一入口其结构要点library tests; import dart:async; import dart:math; import package:http/http.dart; import package:guinness/guinness.dart; import package:swagger/api.dart; part pet_test.dart; part store_test.dart; part user_test.dart; final random new Random(); int newId() { return random.nextInt(999999); } main() { testPetApi(); testStoreApi(); testUserApi(); }值得注意的设计细节三个测试文件通过part指令并入同一 library共享tests.dart中的random与newId()newId()每次生成0 ~ 999998的随机数作为对象 id避免多轮运行间的数据冲突——这正是前面控制台输出中出现957639、525946、29756等随机 404 的原因main()依次调用三个testXxxApi()对应 Pet/Store/User 三组接口。Pet API 测试的典型模式pet_test.dart 覆盖了 Pet API 的 8 个用例这里提取几个代表性模式正向创建-读取闭环it(adds a new pet and gets it by id, () async { var id newId(); await petApi.addPet(new Pet()..id id); var pet await petApi.getPetById(id); expect(pet.id).toEqual(id); });负向用例期望抛出 ApiExceptionit(doesn\t get non-existing pet by id, () { expect(petApi.getPetById(newId())) .toThrowWith(anInstanceOf: ApiException); });这类用例正是控制台中 404 日志的来源——getPetById查询不存在的 id 时客户端抛出ApiException框架记录 404 请求同时断言通过。表单更新与并发测试updates pet with form演示了updatePetWithForm(id, name: ..., status: ...)的表单参数调用finds pets by status则通过Future.wait并发创建三个宠物两个available、一个sold随后断言按状态过滤的结果只包含前两者覆盖了查询参数collectionFormat与异步并发的场景。Store / User API 测试要点store_test.dart 覆盖下单、按 id 查询、删除订单以及库存统计getInventory返回MapString, intuser_test.dart 则覆盖用户创建单个与列表两种方式、更新、删除与登录断言返回字符串包含logged in user session:。三组用例合计 16 个与文档中All 16 tests passed.一一对应。底层支撑ApiClient 的调用与认证机制测试之所以能直接new PetApi()使用依赖的是 swagger-codegen 生成的客户端库。其核心是 swagger-browser-client/lib/api_client.dart 中的ApiClient类值得展开的关键点默认 basePath构造函数默认指向http://petstore.swagger.io/v2见 api_client.dart即测试真实请求的远端服务地址认证预注册构造函数中预先注册了api_keyApiKeyAuthheader 方式键名api_key与petstore_authOAuth两种认证见 api_client.dart统一请求入口invokeAPI拼接 basePath path queryString注入默认请求头与Content-Type并按 method 分发到client.post/put/delete/patch/get对于MultipartRequest如上传图片走client.send流式发送见 api_client.dart认证注入_updateParamsForAuth按调用方传入的authNames查找对应Authentication并调用applyToParams未注册的认证名会抛出ArgumentError见 api_client.dart反序列化_deserialize支持String/int/bool/double基础类型也支持Amount、Pet、User等模型以及ListT、MapString,T泛型递归解析见 api_client.dart。测试中petApi.deletePet(id, apiKey: special-key)之所以能携带api_key头正是认证模块applyToParams在每次请求前写入 header 的结果这也印证了文档所述测试对安全接口的覆盖能力。此外客户端库通过 api.dart 以单一 librarylibrary swagger.api聚合了 3 个 API 实现、8 个模型类与全部认证模块并导出全局单例defaultApiClient测试代码只需import package:swagger/api.dart即可使用全部能力。常见问题与排查建议控制台看不到任何输出确认已打开 DevTools Console而非页面元素面板并等待unittest-suite-wait-for-done出现出现非 404 的错误请求检查远端 Petstore 服务http://petstore.swagger.io/v2是否可达测试为真实网络请求不依赖本地 mockVM 模式下报BrowserClient相关错误请确认已同步完成 api_client.dart 与 api.dart 两处修改二者缺一不可依赖拉取失败swagger库采用本地相对路径../swagger-browser-client依赖移动目录时需同步调整 pubspec.yaml 中的path。小结本示例完整展示了 swagger-codegen 生成 Dart 客户端后开箱即测的流程pub serve 浏览器控制台验证或两处代码切换后在 Dart VM 中直跑。结合 tests.dart 的入口组织、三份测试文件中的正负向用例模式以及 ApiClient 的请求/认证/序列化实现你可以将这套生成 → 运行 → 控制台确认的方法迁移到任意基于 OpenAPI 规范生成的 Dart 客户端项目中。【免费下载链接】swagger-codegenswagger-codegen contains a template-driven engine to generate documentation, API clients and server stubs in different languages by parsing your OpenAPI / Swagger definition.项目地址: https://gitcode.com/gh_mirrors/sw/swagger-codegen创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 使用 swagger-codegen 生成的 Dart 客户端：Petstore 测试套件的运行与原理详解
使用 swagger-codegen 生成的 Dart 客户端Petstore 测试套件的运行与原理详解【免费下载链接】swagger-codegenswagger-codegen contains a template-driven engine to generate documentation, API clients and server stubs in different languages by parsing your OpenAPI / Swagger definition.项目地址: https://gitcode.com/gh_mirrors/sw/swagger-codegen导读本指南以 swagger-codegen 仓库中的 Dart Petstore 客户端测试示例 为核心完整讲解如何运行基于 OpenAPI/Swagger 定义自动生成的 Dart API 客户端测试包括浏览器pub servetests.html与 Dart VM 两种运行方式、期望的测试输出以及底层客户端库ApiClient的调用链与认证机制。读完本文你将能独立复现这套测试流程并理解 swagger-codegen 生成 Dart 客户端时测试代码、库代码与依赖配置之间的关系。测试示例在仓库中的位置与构成该示例位于 samples/client/petstore/dart/petstore是 swagger-codegen 依据 Petstore 规范为 Dart 语言生成的完整测试工程。整个示例由两部分组成petstore 测试工程即本指南的核心目录包含测试入口 test/tests.dart、浏览器宿主页 test/tests.html、针对 Pet/Store/User 三组 API 的测试文件以及工程声明 pubspec.yaml。swagger 客户端库通过pubspec.yaml中的swagger: path: ../swagger-browser-client以本地路径方式依赖即 swagger-browser-client其中包含ApiClient、认证模块、模型类与各 API 实现。工程依赖声明如下pubspec.yamlname: petstore_client version: 1.0.0 description: Petstore client using swagger API library dependencies: swagger: path: ../swagger-browser-client browser: any dev_dependencies: guinness: ^0.1.17其中guinness是测试框架提供describe/it/expect等 BDD 风格断言browser用于浏览器环境而客户端库本身则依赖http: 0.11.1 0.12.0见 swagger-browser-client/pubspec.yaml。方式一在浏览器中运行测试原文档给出的最快验证路径是浏览器方式全程两条命令即可启动 Dart 开发服务器pub serve在浏览器中打开测试宿主页http://127.0.0.1:8080/tests.html打开页面即自动开始执行测试。注意页面本身不会显示任何通过/失败提示——你需要打开浏览器的 JavaScript / Dart 控制台DevTools Console来观察测试进度与结果。原文档明确提示there isNOfeedback!这是这套浏览器测试方案的显著特点一切断言输出都通过print/unittest-suite-*约定写入控制台。tests.html 的宿主逻辑非常简单通过script typeapplication/dart srctests.dart加载测试脚本再由script srcpackages/browser/dart.js完成 Dart 到 JS 的编译与引导。期望的浏览器控制台输出原文档给出了完整的预期输出是判断测试是否全部通过的唯一依据完整继承如下Observatory listening at http://127.0.0.1:39067/ unittest-suite-wait-for-done GET http://petstore.swagger.io/v2/pet/957639 404 (Not Found) GET http://petstore.swagger.io/v2/pet/525946 404 (Not Found) GET http://petstore.swagger.io/v2/store/order/29756 404 (Not Found) GET http://petstore.swagger.io/v2/user/Riddlem325 404 (Not Found) PASS: Pet API adds a new pet and gets it by id PASS: Pet API doesnt get non-existing pet by id PASS: Pet API deletes existing pet by id PASS: Pet API updates pet with form PASS: Pet API updates existing pet PASS: Pet API finds pets by status PASS: Pet API finds pets by tag PASS: Pet API uploads a pet image PASS: Store API places an order and gets it by id PASS: Store API deletes an order PASS: Store API gets the store inventory PASS: User API creates a user PASS: User API creates users with list input PASS: User API updates a user PASS: User API deletes a user PASS: User API logs a user in All 16 tests passed. unittest-suite-success需要注意几点解读输出中穿插的 4 条404 (Not Found)是预期行为来自测试中查询不存在对象并期望抛出ApiException的负向用例详见下文测试源码解析并非测试失败unittest-suite-wait-for-done表示测试套件已就绪并等待异步用例完成最后的All 16 tests passed.与unittest-suite-success才是全部通过的确证。方式二在 Dart VM 中运行测试若不想依赖浏览器环境可以改为在 Dart VM命令行中直接执行测试。原文档提供了两条并列的切换路径任选其一即可。切换方案 A使用生成脚本README 提及原文档描述为修改bin/dart-petstore.sh取消注释其中的 vm 选项行运行bin/dart-petstore.sh。需要说明的是当前仓库快照的samples/client/petstore/dart/petstore目录下并未包含该脚本仅见 test、README.md 与 pubspec.yaml因此此方案适用于完整生成的工程副本实际使用时请以你本地生成结果中的脚本内容为准。切换方案 B直接修改客户端库代码仓库可验证这是当前仓库内可完整验证的方式共两步在 swagger-browser-client/lib/api_client.dart 中将默认 HTTP 客户端从浏览器实现切换为纯 Dart VM 实现// 原来浏览器环境 var client new BrowserClient(); // 改为VM 环境 var client new Client();在 swagger-browser-client/lib/api.dart 中删除对浏览器客户端的导入import package:http/browser_client.dart;完成切换后运行dart test/tests.dart即可在 VM 中直接执行全部测试。其原理在于BrowserClient依赖浏览器的XMLHttpRequest能力只能运行于 dart2js 编译后的浏览器环境而package:http的Client()基于dart:io的HttpClient可在命令行 VM 中直连远端 API。测试入口与用例源码解析入口tests.dart 的组织方式test/tests.dart 是全部测试的唯一入口其结构要点library tests; import dart:async; import dart:math; import package:http/http.dart; import package:guinness/guinness.dart; import package:swagger/api.dart; part pet_test.dart; part store_test.dart; part user_test.dart; final random new Random(); int newId() { return random.nextInt(999999); } main() { testPetApi(); testStoreApi(); testUserApi(); }值得注意的设计细节三个测试文件通过part指令并入同一 library共享tests.dart中的random与newId()newId()每次生成0 ~ 999998的随机数作为对象 id避免多轮运行间的数据冲突——这正是前面控制台输出中出现957639、525946、29756等随机 404 的原因main()依次调用三个testXxxApi()对应 Pet/Store/User 三组接口。Pet API 测试的典型模式pet_test.dart 覆盖了 Pet API 的 8 个用例这里提取几个代表性模式正向创建-读取闭环it(adds a new pet and gets it by id, () async { var id newId(); await petApi.addPet(new Pet()..id id); var pet await petApi.getPetById(id); expect(pet.id).toEqual(id); });负向用例期望抛出 ApiExceptionit(doesn\t get non-existing pet by id, () { expect(petApi.getPetById(newId())) .toThrowWith(anInstanceOf: ApiException); });这类用例正是控制台中 404 日志的来源——getPetById查询不存在的 id 时客户端抛出ApiException框架记录 404 请求同时断言通过。表单更新与并发测试updates pet with form演示了updatePetWithForm(id, name: ..., status: ...)的表单参数调用finds pets by status则通过Future.wait并发创建三个宠物两个available、一个sold随后断言按状态过滤的结果只包含前两者覆盖了查询参数collectionFormat与异步并发的场景。Store / User API 测试要点store_test.dart 覆盖下单、按 id 查询、删除订单以及库存统计getInventory返回MapString, intuser_test.dart 则覆盖用户创建单个与列表两种方式、更新、删除与登录断言返回字符串包含logged in user session:。三组用例合计 16 个与文档中All 16 tests passed.一一对应。底层支撑ApiClient 的调用与认证机制测试之所以能直接new PetApi()使用依赖的是 swagger-codegen 生成的客户端库。其核心是 swagger-browser-client/lib/api_client.dart 中的ApiClient类值得展开的关键点默认 basePath构造函数默认指向http://petstore.swagger.io/v2见 api_client.dart即测试真实请求的远端服务地址认证预注册构造函数中预先注册了api_keyApiKeyAuthheader 方式键名api_key与petstore_authOAuth两种认证见 api_client.dart统一请求入口invokeAPI拼接 basePath path queryString注入默认请求头与Content-Type并按 method 分发到client.post/put/delete/patch/get对于MultipartRequest如上传图片走client.send流式发送见 api_client.dart认证注入_updateParamsForAuth按调用方传入的authNames查找对应Authentication并调用applyToParams未注册的认证名会抛出ArgumentError见 api_client.dart反序列化_deserialize支持String/int/bool/double基础类型也支持Amount、Pet、User等模型以及ListT、MapString,T泛型递归解析见 api_client.dart。测试中petApi.deletePet(id, apiKey: special-key)之所以能携带api_key头正是认证模块applyToParams在每次请求前写入 header 的结果这也印证了文档所述测试对安全接口的覆盖能力。此外客户端库通过 api.dart 以单一 librarylibrary swagger.api聚合了 3 个 API 实现、8 个模型类与全部认证模块并导出全局单例defaultApiClient测试代码只需import package:swagger/api.dart即可使用全部能力。常见问题与排查建议控制台看不到任何输出确认已打开 DevTools Console而非页面元素面板并等待unittest-suite-wait-for-done出现出现非 404 的错误请求检查远端 Petstore 服务http://petstore.swagger.io/v2是否可达测试为真实网络请求不依赖本地 mockVM 模式下报BrowserClient相关错误请确认已同步完成 api_client.dart 与 api.dart 两处修改二者缺一不可依赖拉取失败swagger库采用本地相对路径../swagger-browser-client依赖移动目录时需同步调整 pubspec.yaml 中的path。小结本示例完整展示了 swagger-codegen 生成 Dart 客户端后开箱即测的流程pub serve 浏览器控制台验证或两处代码切换后在 Dart VM 中直跑。结合 tests.dart 的入口组织、三份测试文件中的正负向用例模式以及 ApiClient 的请求/认证/序列化实现你可以将这套生成 → 运行 → 控制台确认的方法迁移到任意基于 OpenAPI 规范生成的 Dart 客户端项目中。【免费下载链接】swagger-codegenswagger-codegen contains a template-driven engine to generate documentation, API clients and server stubs in different languages by parsing your OpenAPI / Swagger definition.项目地址: https://gitcode.com/gh_mirrors/sw/swagger-codegen创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考