Swagger Codegen 生成 Dart / Flutter 客户端实战以 swagger-codegen Petstore 包为例的安装、认证与 API 调用指南【免费下载链接】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 客户端示例samples/client/petstore/dart/flutter_petstore/swagger/README.md为主体完整讲解一个由 Swagger Codegen 的dart生成器产出的 Dart API 客户端包的结构、安装方式、认证配置与调用方法。读完本文你将掌握如何把这类生成包接入自己的 Dart / Flutter 项目理解 API Key 与 OAuth 认证在生成代码中的落地方式并学会通过DartClientCodegen的配置项控制生成产物的名称、版本与枚举处理行为。生成产物概览这个包是什么swagger包是 Swagger Codegen 基于 Petstore 示例服务自动生成的 Dart 客户端库其元信息记录在生成包的 README 中API 版本1.0.0对应 OpenAPI/Swagger 规格中声明的服务版本构建生成器io.swagger.codegen.languages.DartClientCodegen示例服务Swagger Petstore所有 URL 均以http://petstore.swagger.io/v2为基准生成包在仓库中的实际目录结构如下目录树swagger/ ├── README.md # 本指南对应的生成说明文档 ├── pubspec.yaml # Dart 包清单name: swagger, version: 1.0.0 ├── git_push.sh # 一键推送到远程仓库的脚本 ├── docs/ # 按 API/模型生成的 Markdown 文档 │ ├── PetApi.md / StoreApi.md / UserApi.md │ └── Amount.md / ApiResponse.md / Category.md / Currency.md / Order.md / Pet.md / Tag.md / User.md └── lib/ ├── api.dart # 库聚合入口 defaultApiClient ├── api_client.dart # HTTP 客户端认证、序列化、请求分发 ├── api_helper.dart # 集合格式转换等辅助函数 ├── api_exception.dart # 统一异常类型 ├── api/ # pet_api.dart / store_api.dart / user_api.dart ├── auth/ # authentication / api_key_auth / oauth / http_basic_auth └── model/ # 8 个模型类均提供 fromJson / toJson这一布局由生成器源码直接决定DartClientCodegen在processOpts()中注册了api_client.dart、api_exception.dart、api_helper.dart、api.dart、四个 auth 文件、pubspec.yaml、.analysis_options、git_push.sh、.gitignore与README.md等支撑文件并将模型与 API 模板分别映射为.dart文件见 DartClientCodegen.java。环境要求README 明确给出生成包的运行前提Dart 1.20.0 或更高版本或者Flutter 0.0.20 或更高版本实际生成的 pubspec.yaml 只声明了一个外部依赖name: swagger version: 1.0.0 description: Swagger API client dependencies: http: 0.11.1 0.12.0注意http依赖使用宽松区间约束0.11.1 0.12.0因此该包可被pub get解析到区间内的任意兼容版本在接入你自己的项目时无需担心版本冲突。安装与使用README 提供了两种接入方式均通过编辑目标项目的pubspec.yaml完成。方式一通过 Git 仓库引入当生成包发布到 Git 仓库后在你的项目pubspec.yaml中声明name: swagger version: 1.0.0 description: Swagger API client dependencies: swagger: git: https://github.com/GIT_USER_ID/GIT_REPO_ID.git version: any生成包自带的 git_push.sh 正是为生成代码后推送到自己的 Git 仓库、再以 Git 依赖方式复用这一工作流准备的发布脚本。示例中的GIT_USER_ID/GIT_REPO_ID是模板占位符实际使用时请替换为你自己的用户名与仓库名。方式二本地路径引入在本地开发阶段可直接以路径方式引用生成包的目录dependencies: swagger: path: /path/to/swagger将/path/to/swagger替换为swagger包在本机上的实际路径即可。之后在项目根目录执行pub get完成依赖解析。快速开始第一个 API 调用README 以PetApi.addPet为例演示了完整调用流程先配置认证再构造请求体最后调用方法并捕获异常。import package:swagger/api.dart; // TODO 配置 OAuth2 访问令牌以通过 petstore_auth 授权 // swagger.api.Configuration.accessToken YOUR_ACCESS_TOKEN; var api_instance new PetApi(); var body new Pet(); // Pet | 需要添加到商店的宠物对象 try { api_instance.addPet(body); } catch (e) { print(Exception when calling PetApi-addPet: $e\n); }代码背后的实现机制从生成源码看调用链可拆解为三层API 方法层PetApi.addPet位于 pet_api.dart先校验必填参数body null时抛出ApiException(400, Missing required param: body)再拼接路径/pet、选取application/json作为 Content-Type声明authNames [petstore_auth]最终委托给ApiClient.invokeAPI。客户端层ApiClient.invokeAPIapi_client.dart依次完成按authNames注入认证参数 → 拼装 query string → 合并默认请求头 → 根据contentType决定走MultipartRequest还是普通POST/PUT/DELETE/PATCH/GET分发。异常层HTTP 状态码 400时统一抛出ApiException(statusCode, body)便于上层按业务捕获处理。关于更新与多表单等特殊端点上传图片类接口uploadFilePOST /pet/{petId}/uploadImage走multipart/form-data分支生成代码会自动构造MultipartRequest并携带文件与表单字段删除类接口如deletePet通过.replaceAll({petId}, petId.toString())在路径中内插路径参数同时将api_key写入请求头集合查询参数如findPetsByStatus的status经由api_helper.dart中的_convertParametersForCollectionFormat按csv等格式展开为 query 参数。API 端点一览所有 URL 均相对于http://petstore.swagger.io/v2。README 中列出了完整的 19 个端点覆盖三个 API 类PetApi方法HTTP 请求描述addPetPOST/pet向商店添加新宠物deletePetDELETE/pet/{petId}删除宠物findPetsByStatusGET/pet/findByStatus按状态查询宠物支持逗号分隔多值findPetsByTagsGET/pet/findByTags按标签查询宠物getPetByIdGET/pet/{petId}按 ID 查找宠物updatePetPUT/pet更新已有宠物updatePetWithFormPOST/pet/{petId}以表单数据更新宠物uploadFilePOST/pet/{petId}/uploadImage上传图片StoreApi方法HTTP 请求描述deleteOrderDELETE/store/order/{orderId}按 ID 删除订单getInventoryGET/store/inventory按状态返回宠物库存getOrderByIdGET/store/order/{orderId}按 ID 查询订单placeOrderPOST/store/order下单UserApi方法HTTP 请求描述createUserPOST/user创建用户createUsersWithArrayInputPOST/user/createWithArray用数组批量创建用户createUsersWithListInputPOST/user/createWithList用列表批量创建用户deleteUserDELETE/user/{username}删除用户getUserByNameGET/user/{username}按用户名获取用户loginUserGET/user/login用户登录logoutUserGET/user/logout用户登出updateUserPUT/user/{username}更新用户每个端点的参数表、请求/响应示例、错误码说明详见 docs 目录下对应的PetApi.md、StoreApi.md、UserApi.md文档。模型Models生成包共包含 8 个模型类每个均对应docs/下一份 Markdown 文档并实现了fromJson/toJson序列化接口AmountApiResponseCategoryCurrencyOrderPetTagUser模型类的反序列化由ApiClient._deserialize统一处理api_client.dart基础类型String/int/bool/double走类型转换模型类型Pet/Order/User等走fromJsonList...与MapString, ...通过正则解析泛型后递归反序列化任何失败都会包装为ApiException.withInner(500, ...)抛出。认证AuthorizationREADME 文档声明了两种认证方案生成代码中均有对应实现且在ApiClient构造时自动注册api_keyAPI Key类型API key参数名api_key位置HTTP Header实现位于 api_key_auth.dartApiKeyAuth构造时接收location与paramNameapplyToParams时按 location 分别注入 query 或 header若设置了apiKeyPrefix则以$apiKeyPrefix $apiKey的形式携带前缀。在本示例中ApiClient构造函数将其注册为_authentications[api_key] new ApiKeyAuth(header, api_key)见 api_client.dart。README 提示测试该示例服务时可直接使用 API keyspecial-key验证授权过滤器。petstore_authOAuth2类型OAuthFlowimplicit隐式授权授权地址http://petstore.swagger.io/api/oauth/dialogScopeswrite:pets修改账户中的宠物read:pets读取你的宠物实现位于 oauth.dartOAuth持有一个accessTokenapplyToParams时将其以Authorization: Bearer token注入请求头并提供setAccessToken供运行时更新令牌。快速开始示例中被注释掉的swagger.api.Configuration.accessToken YOUR_ACCESS_TOKEN正是此用途此外ApiClient还提供了全局便捷方法setAccessToken会遍历所有已注册认证并将令牌写入所有OAuth实例api_client.dart。认证在请求时按需生效每个 API 方法都会声明自己的authNames如addPet声明[petstore_auth]invokeAPI通过_updateParamsForAuth只对声明的认证执行applyToParams若声明了未注册的认证名则抛出ArgumentErrorapi_client.dart。从生成器源码看包的定制能力DartClientCodegenDartClientCodegen.java定义了该生成包的全部可配置项与命名规则了解它们可以让你在自行生成客户端时精确控制产物CLI 配置项常量名默认值作用browserClientBROWSER_CLIENTtrue是否为浏览器端客户端传递给模板pubNamePUB_NAMEswagger生成的 pubspec 中的包名pubVersionPUB_VERSION1.0.0生成的 pubspec 中的版本号pubDescriptionPUB_DESCRIPTIONSwagger API client生成的 pubspec 中的描述useEnumExtensionUSE_ENUM_EXTENSIONfalse是否启用x-enum-values扩展生成枚举sourceFolderSOURCE_FOLDER生成代码的源目录对应的命令行用法形如java -jar modules/swagger-codegen-cli/target/swagger-codegen-cli.jar generate \ -i petstore.yaml \ -l dart \ -o generated-code/dart \ --additional-properties pubNamemy_client,pubVersion1.0.0,pubDescriptionMy API client生成器还定义了一系列类型映射规则DartClientCodegen.java可直接印证生成产物中的 Dart 类型来源boolean→boolstring/char→Stringinteger/long/short→intnumber→numfloat/double→doublearray/Array→Listmap→Mapdate/Date→DateTimeFile→MultipartFilebinary与ByteArray暂以String兜底命名方面toVarName会把pet_id之类下划线命名转为petId驼峰形式数字开头补n前缀Dart 保留字class、return、switch等自动追加下划线转义toModelName对保留字模型名加model_前缀后再驼峰化。枚举值经toEnumVarName将非法字符替换为下划线数字枚举加Number前缀并可通过useEnumExtension支持规格中的x-enum-values扩展见 DartClientCodegen.java。包作者与后续查阅生成包 README 中记录的示例服务维护者为apiteamswagger.io。进一步查阅每个端点与模型的字段级说明请直接浏览 docs 目录下的 Markdown 文档若要查看 Flutter 工程形态的完整示例含 iOS/Android 工程骨架可参考同目录的上层示例 flutter_petstore而生成该 Dart 包的其余两个变体swagger与swagger-browser-client位于 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 / Flutter 客户端实战：以 swagger-codegen Petstore 包为例的安装、认证与 API 调用指南
Swagger Codegen 生成 Dart / Flutter 客户端实战以 swagger-codegen Petstore 包为例的安装、认证与 API 调用指南【免费下载链接】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 客户端示例samples/client/petstore/dart/flutter_petstore/swagger/README.md为主体完整讲解一个由 Swagger Codegen 的dart生成器产出的 Dart API 客户端包的结构、安装方式、认证配置与调用方法。读完本文你将掌握如何把这类生成包接入自己的 Dart / Flutter 项目理解 API Key 与 OAuth 认证在生成代码中的落地方式并学会通过DartClientCodegen的配置项控制生成产物的名称、版本与枚举处理行为。生成产物概览这个包是什么swagger包是 Swagger Codegen 基于 Petstore 示例服务自动生成的 Dart 客户端库其元信息记录在生成包的 README 中API 版本1.0.0对应 OpenAPI/Swagger 规格中声明的服务版本构建生成器io.swagger.codegen.languages.DartClientCodegen示例服务Swagger Petstore所有 URL 均以http://petstore.swagger.io/v2为基准生成包在仓库中的实际目录结构如下目录树swagger/ ├── README.md # 本指南对应的生成说明文档 ├── pubspec.yaml # Dart 包清单name: swagger, version: 1.0.0 ├── git_push.sh # 一键推送到远程仓库的脚本 ├── docs/ # 按 API/模型生成的 Markdown 文档 │ ├── PetApi.md / StoreApi.md / UserApi.md │ └── Amount.md / ApiResponse.md / Category.md / Currency.md / Order.md / Pet.md / Tag.md / User.md └── lib/ ├── api.dart # 库聚合入口 defaultApiClient ├── api_client.dart # HTTP 客户端认证、序列化、请求分发 ├── api_helper.dart # 集合格式转换等辅助函数 ├── api_exception.dart # 统一异常类型 ├── api/ # pet_api.dart / store_api.dart / user_api.dart ├── auth/ # authentication / api_key_auth / oauth / http_basic_auth └── model/ # 8 个模型类均提供 fromJson / toJson这一布局由生成器源码直接决定DartClientCodegen在processOpts()中注册了api_client.dart、api_exception.dart、api_helper.dart、api.dart、四个 auth 文件、pubspec.yaml、.analysis_options、git_push.sh、.gitignore与README.md等支撑文件并将模型与 API 模板分别映射为.dart文件见 DartClientCodegen.java。环境要求README 明确给出生成包的运行前提Dart 1.20.0 或更高版本或者Flutter 0.0.20 或更高版本实际生成的 pubspec.yaml 只声明了一个外部依赖name: swagger version: 1.0.0 description: Swagger API client dependencies: http: 0.11.1 0.12.0注意http依赖使用宽松区间约束0.11.1 0.12.0因此该包可被pub get解析到区间内的任意兼容版本在接入你自己的项目时无需担心版本冲突。安装与使用README 提供了两种接入方式均通过编辑目标项目的pubspec.yaml完成。方式一通过 Git 仓库引入当生成包发布到 Git 仓库后在你的项目pubspec.yaml中声明name: swagger version: 1.0.0 description: Swagger API client dependencies: swagger: git: https://github.com/GIT_USER_ID/GIT_REPO_ID.git version: any生成包自带的 git_push.sh 正是为生成代码后推送到自己的 Git 仓库、再以 Git 依赖方式复用这一工作流准备的发布脚本。示例中的GIT_USER_ID/GIT_REPO_ID是模板占位符实际使用时请替换为你自己的用户名与仓库名。方式二本地路径引入在本地开发阶段可直接以路径方式引用生成包的目录dependencies: swagger: path: /path/to/swagger将/path/to/swagger替换为swagger包在本机上的实际路径即可。之后在项目根目录执行pub get完成依赖解析。快速开始第一个 API 调用README 以PetApi.addPet为例演示了完整调用流程先配置认证再构造请求体最后调用方法并捕获异常。import package:swagger/api.dart; // TODO 配置 OAuth2 访问令牌以通过 petstore_auth 授权 // swagger.api.Configuration.accessToken YOUR_ACCESS_TOKEN; var api_instance new PetApi(); var body new Pet(); // Pet | 需要添加到商店的宠物对象 try { api_instance.addPet(body); } catch (e) { print(Exception when calling PetApi-addPet: $e\n); }代码背后的实现机制从生成源码看调用链可拆解为三层API 方法层PetApi.addPet位于 pet_api.dart先校验必填参数body null时抛出ApiException(400, Missing required param: body)再拼接路径/pet、选取application/json作为 Content-Type声明authNames [petstore_auth]最终委托给ApiClient.invokeAPI。客户端层ApiClient.invokeAPIapi_client.dart依次完成按authNames注入认证参数 → 拼装 query string → 合并默认请求头 → 根据contentType决定走MultipartRequest还是普通POST/PUT/DELETE/PATCH/GET分发。异常层HTTP 状态码 400时统一抛出ApiException(statusCode, body)便于上层按业务捕获处理。关于更新与多表单等特殊端点上传图片类接口uploadFilePOST /pet/{petId}/uploadImage走multipart/form-data分支生成代码会自动构造MultipartRequest并携带文件与表单字段删除类接口如deletePet通过.replaceAll({petId}, petId.toString())在路径中内插路径参数同时将api_key写入请求头集合查询参数如findPetsByStatus的status经由api_helper.dart中的_convertParametersForCollectionFormat按csv等格式展开为 query 参数。API 端点一览所有 URL 均相对于http://petstore.swagger.io/v2。README 中列出了完整的 19 个端点覆盖三个 API 类PetApi方法HTTP 请求描述addPetPOST/pet向商店添加新宠物deletePetDELETE/pet/{petId}删除宠物findPetsByStatusGET/pet/findByStatus按状态查询宠物支持逗号分隔多值findPetsByTagsGET/pet/findByTags按标签查询宠物getPetByIdGET/pet/{petId}按 ID 查找宠物updatePetPUT/pet更新已有宠物updatePetWithFormPOST/pet/{petId}以表单数据更新宠物uploadFilePOST/pet/{petId}/uploadImage上传图片StoreApi方法HTTP 请求描述deleteOrderDELETE/store/order/{orderId}按 ID 删除订单getInventoryGET/store/inventory按状态返回宠物库存getOrderByIdGET/store/order/{orderId}按 ID 查询订单placeOrderPOST/store/order下单UserApi方法HTTP 请求描述createUserPOST/user创建用户createUsersWithArrayInputPOST/user/createWithArray用数组批量创建用户createUsersWithListInputPOST/user/createWithList用列表批量创建用户deleteUserDELETE/user/{username}删除用户getUserByNameGET/user/{username}按用户名获取用户loginUserGET/user/login用户登录logoutUserGET/user/logout用户登出updateUserPUT/user/{username}更新用户每个端点的参数表、请求/响应示例、错误码说明详见 docs 目录下对应的PetApi.md、StoreApi.md、UserApi.md文档。模型Models生成包共包含 8 个模型类每个均对应docs/下一份 Markdown 文档并实现了fromJson/toJson序列化接口AmountApiResponseCategoryCurrencyOrderPetTagUser模型类的反序列化由ApiClient._deserialize统一处理api_client.dart基础类型String/int/bool/double走类型转换模型类型Pet/Order/User等走fromJsonList...与MapString, ...通过正则解析泛型后递归反序列化任何失败都会包装为ApiException.withInner(500, ...)抛出。认证AuthorizationREADME 文档声明了两种认证方案生成代码中均有对应实现且在ApiClient构造时自动注册api_keyAPI Key类型API key参数名api_key位置HTTP Header实现位于 api_key_auth.dartApiKeyAuth构造时接收location与paramNameapplyToParams时按 location 分别注入 query 或 header若设置了apiKeyPrefix则以$apiKeyPrefix $apiKey的形式携带前缀。在本示例中ApiClient构造函数将其注册为_authentications[api_key] new ApiKeyAuth(header, api_key)见 api_client.dart。README 提示测试该示例服务时可直接使用 API keyspecial-key验证授权过滤器。petstore_authOAuth2类型OAuthFlowimplicit隐式授权授权地址http://petstore.swagger.io/api/oauth/dialogScopeswrite:pets修改账户中的宠物read:pets读取你的宠物实现位于 oauth.dartOAuth持有一个accessTokenapplyToParams时将其以Authorization: Bearer token注入请求头并提供setAccessToken供运行时更新令牌。快速开始示例中被注释掉的swagger.api.Configuration.accessToken YOUR_ACCESS_TOKEN正是此用途此外ApiClient还提供了全局便捷方法setAccessToken会遍历所有已注册认证并将令牌写入所有OAuth实例api_client.dart。认证在请求时按需生效每个 API 方法都会声明自己的authNames如addPet声明[petstore_auth]invokeAPI通过_updateParamsForAuth只对声明的认证执行applyToParams若声明了未注册的认证名则抛出ArgumentErrorapi_client.dart。从生成器源码看包的定制能力DartClientCodegenDartClientCodegen.java定义了该生成包的全部可配置项与命名规则了解它们可以让你在自行生成客户端时精确控制产物CLI 配置项常量名默认值作用browserClientBROWSER_CLIENTtrue是否为浏览器端客户端传递给模板pubNamePUB_NAMEswagger生成的 pubspec 中的包名pubVersionPUB_VERSION1.0.0生成的 pubspec 中的版本号pubDescriptionPUB_DESCRIPTIONSwagger API client生成的 pubspec 中的描述useEnumExtensionUSE_ENUM_EXTENSIONfalse是否启用x-enum-values扩展生成枚举sourceFolderSOURCE_FOLDER生成代码的源目录对应的命令行用法形如java -jar modules/swagger-codegen-cli/target/swagger-codegen-cli.jar generate \ -i petstore.yaml \ -l dart \ -o generated-code/dart \ --additional-properties pubNamemy_client,pubVersion1.0.0,pubDescriptionMy API client生成器还定义了一系列类型映射规则DartClientCodegen.java可直接印证生成产物中的 Dart 类型来源boolean→boolstring/char→Stringinteger/long/short→intnumber→numfloat/double→doublearray/Array→Listmap→Mapdate/Date→DateTimeFile→MultipartFilebinary与ByteArray暂以String兜底命名方面toVarName会把pet_id之类下划线命名转为petId驼峰形式数字开头补n前缀Dart 保留字class、return、switch等自动追加下划线转义toModelName对保留字模型名加model_前缀后再驼峰化。枚举值经toEnumVarName将非法字符替换为下划线数字枚举加Number前缀并可通过useEnumExtension支持规格中的x-enum-values扩展见 DartClientCodegen.java。包作者与后续查阅生成包 README 中记录的示例服务维护者为apiteamswagger.io。进一步查阅每个端点与模型的字段级说明请直接浏览 docs 目录下的 Markdown 文档若要查看 Flutter 工程形态的完整示例含 iOS/Android 工程骨架可参考同目录的上层示例 flutter_petstore而生成该 Dart 包的其余两个变体swagger与swagger-browser-client位于 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），仅供参考