Swagger Codegen 生成 Dart 客户端全指南：以 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/swagger/README.md为核心完整讲解如何把生成的 Dart API 客户端引入项目、完成环境配置、调用 Petstore 示例接口并深入剖析底层DartClientCodegen生成器与ApiClient运行时的实现原理。读完本文你将掌握生成式 Dart 客户端的目录结构、pub 依赖接入方式、OAuth2 / API Key 两种鉴权配置以及源码级的方法调用链路。生成产物概览swagger Dart 客户端包该示例包是对 Petstore 示例服务Swagger 2.0 定义执行代码生成后的产物README 中明确记录了元信息API 版本1.0.0构建包Build packageio.swagger.codegen.languages.DartClientCodegen即此包由 Swagger Codegen 的 Dart 语言生成器产出对应的实现类位于 DartClientCodegen.java。从生成的目录结构samples/client/petstore/dart/swagger可以看到标准的 Dart 包组织方式lib/api.dart库入口文件通过 Dart 的part/part of机制聚合全部代码lib/api/按业务域划分的 API 类pet_api.dart、store_api.dart、user_api.dartlib/model/数据模型类Pet、Order、User、Category、Tag等 8 个模型lib/auth/鉴权实现api_key_auth.dart、oauth.dart、http_basic_auth.dart、authentication.dartlib/api_client.dart核心 HTTP 客户端封装pubspec.yaml包描述与依赖声明docs/自动生成的 API 与模型 Markdown 文档。环境要求Requirements官方 README 明确要求如下运行环境二者满足其一即可Dart 1.20.0 或更高版本或 Flutter 0.0.20 或更高版本。生成的pubspec.yaml见 pubspec.yaml对 HTTP 依赖做了版本约束name: swagger version: 1.0.0 description: Swagger API client dependencies: http: 0.11.1 0.12.0这里的name、version、description均可在生成时通过 CLI 参数定制详见下文“生成器 CLI 参数”小节http包是底层请求库约束为 0.11.x 系列。安装与引入Installation UsageREADME 给出了两种接入方式均通过编辑目标项目的pubspec.yaml完成。方式一通过 Git 仓库引入如果该 Dart 包已发布到 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_USER_ID与GIT_REPO_ID为发布时的占位符实际使用时需替换为真实的仓库地址。方式二通过本地路径引入在本地开发或尚未发布时可直接引用本机路径dependencies: swagger: path: /path/to/swagger将/path/to/swagger替换为生成包所在的实际目录即可。快速开始调用第一个 APIREADME 的 “Getting Started” 章节给出了最简调用示例核心步骤如下import package:swagger/api.dart; // TODO Configure OAuth2 access token for authorization: petstore_auth //swagger.api.Configuration.accessToken YOUR_ACCESS_TOKEN; var api_instance new PetApi(); var body new Pet(); // Pet | Pet object that needs to be added to the store try { api_instance.addPet(body); } catch (e) { print(Exception when calling PetApi-addPet: $e\n); }入口导入统一使用package:swagger/api.dartPetApi构造时不传参默认复用全局defaultApiClient该对象定义于 lib/api.dart代码为ApiClient defaultApiClient new ApiClient();调用方法为异步Future返回数据与 HTTP 状态码大于等于 400 的异常均由调用方处理。方法级调用细节以findPetsByStatus为例pet_api.dart 中可以看到生成方法的标准模式FutureListPet findPetsByStatus(ListString status) async { Object postBody null; // verify required params are set if(status null) { throw new ApiException(400, Missing required param: status); } String path /pet/findByStatus.replaceAll({format},json); ListQueryParam queryParams []; ... queryParams.addAll(_convertParametersForCollectionFormat(csv, status, status)); ... var response await apiClient.invokeAPI(path, GET, queryParams, postBody, headerParams, formParams, contentType, authNames); if(response.statusCode 400) { throw new ApiException(response.statusCode, response.body); } else if(response.body ! null) { return (apiClient.deserialize(response.body, ListPet) as List).map((item) item as Pet).toList(); } else { return null; } }可以总结出生成代码的统一行为必填参数为空时抛出ApiException(400, Missing required param: xxx)路径模板中的{petId}等占位符被替换为实际值{format}默认替换为json集合参数通过_convertParametersForCollectionFormat按csv等 collectionFormat 拼装为查询参数所有请求统一走ApiClient.invokeAPI响应statusCode 400一律抛异常否则由apiClient.deserialize反序列化为强类型模型。API Endpoints 一览所有 URI 均相对于基础地址http://petstore.swagger.io/v2该地址在 api_client.dart 中以ApiClient({this.basePath: http://petstore.swagger.io/v2})作为默认值也可在构造时覆盖。三个 API 类共 20 个方法如下PetApidocs/PetApi.md方法HTTP 请求描述addPet(body)POST/pet新增宠物deletePet(petId, [apiKey])DELETE/pet/{petId}删除宠物findPetsByStatus(status)GET/pet/findByStatus按状态查询宠物findPetsByTags(tags)GET/pet/findByTags按标签查询宠物getPetById(petId)GET/pet/{petId}按 ID 查找宠物updatePet(body)PUT/pet更新已有宠物updatePetWithForm(petId, [name], [status])POST/pet/{petId}表单更新宠物uploadFile(petId, [additionalMetadata], [file])POST/pet/{petId}/uploadImage上传图片StoreApidocs/StoreApi.md方法HTTP 请求描述deleteOrder(orderId)DELETE/store/order/{orderId}按 ID 删除订单getInventory()GET/store/inventory返回库存getOrderById(orderId)GET/store/order/{orderId}按 ID 查询订单placeOrder(body)POST/store/order下单UserApidocs/UserApi.md方法HTTP 请求描述createUser(body)POST/user创建用户createUsersWithArrayInput(body)POST/user/createWithArray用数组批量创建用户createUsersWithListInput(body)POST/user/createWithList用列表批量创建用户deleteUser(username)DELETE/user/{username}删除用户getUserByName(username)GET/user/{username}按用户名查询用户loginUser(username, password)GET/user/login用户登录logoutUser()GET/user/logout用户登出updateUser(username, body)PUT/user/{username}更新用户数据模型Documentation For Models生成包共包含 8 个模型类各自的属性与约束说明见docs/下的对应文档AmountApiResponseCategoryCurrencyOrderPetTagUser以 Pet 为例模型文档记录了每个字段的 Dart 类型、必填性与默认值属性类型说明备注idint[optional]categoryCategory[optional]nameString必填photoUrlsListString默认[]tagsListTag[optional] 默认[]statusStringpet status in the store[optional]模型类位于 lib/model每个类都实现了fromJson/toJson由ApiClient的反序列化分发机制调用。鉴权方式Documentation For AuthorizationREADME 记录了 Petstore 示例服务声明的两种安全方案生成代码在 lib/auth 中分别实现。api_keyAPI Key 鉴权类型API key参数名api_key位置HTTP header对应实现类ApiKeyAuthapi_key_auth.dart当设置了apiKey后会在请求头中写入api_key头若同时设置了apiKeyPrefix则拼接为$apiKeyPrefix $apiKey例如Bearer xxx。在 Petstore 示例中getPetById使用此鉴权README 注释提示使用测试 keyspecial-key即可通过鉴权过滤。petstore_authOAuth2 隐式授权类型OAuthFlowimplicit隐式Authorization URLhttp://petstore.swagger.io/api/oauth/dialogScopeswrite:petsmodify pets in your account修改账户内的宠物read:petsread your pets读取你的宠物对应实现类OAuthoauth.dart持有accessToken在applyToParams中向请求头写入Authorization: Bearer token通过setAccessToken更新 token。多数写操作addPet、updatePet、uploadFile等都声明需要petstore_auth授权。鉴权在运行时如何生效api_client.dart 的构造函数按名称注册鉴权器ApiClient({this.basePath: http://petstore.swagger.io/v2}) { _authentications[api_key] new ApiKeyAuth(header, api_key); _authentications[petstore_auth] new OAuth(); }每次请求前invokeAPI先调用_updateParamsForAuth(authNames, queryParams, headerParams)根据方法声明的authNames列表找到对应鉴权器并执行applyToParams。若引用未注册的鉴权名会抛出ArgumentError(Authentication undefined: ...)。此外setAccessToken会遍历所有注册的鉴权器统一为OAuth类型设置 token方便在运行时切换凭据。源码视角客户端是如何生成的生成器 CLI 参数DartClientCodegen.java 定义了dart生成器可通过 CLI 的-D或配置传入以下选项CLI 选项说明默认值browserClient是否为浏览器端客户端truepubName生成pubspec.yaml中的包名swaggerpubVersion生成pubspec.yaml中的版本号1.0.0pubDescription生成pubspec.yaml中的描述Swagger API clientuseEnumExtension是否允许使用x-enum-values扩展定义枚举falsesourceFolder生成代码的源目录空即包根目录生成器还会将apiDocPath、modelDocPath暴露给 Mustache 模板默认均为docs/README、pubspec.yaml、api_client.dart、各鉴权文件等均由supportingFiles中的模板渲染产出。当前示例包的pubspec.yaml名称/版本/描述与生成器默认值完全一致可验证上述默认参数的实际效果。类型映射生成器内置了 Swagger 类型到 Dart 类型的映射表示例包括Swagger 类型Dart 类型booleanboolstring/charStringinteger/int/long/shortintnumbernumfloat/doubledoublearray/ListListmapMapdate/DateDateTimeFileMultipartFilebinary/ByteArrayString作为临时方案集合与映射在getTypeDeclaration中被递归包装为ListT/MapString, T这与 api_client.dart 中_deserialize用正则^List(.*)$、^MapString,(.*)$解析目标类型并递归反序列化的逻辑一一对应。命名与编码规则属性名、参数名统一驼峰化pet_id→petId数字开头加n前缀命中 Dart 保留字时追加下划线转义escapeReservedWord方法名operationId同样驼峰化保留字加call_前缀模型名camelize首字母大写保留字加model_前缀例如return→ModelReturn文件名转下划线命名。请求生命周期一次 HTTP 调用的完整链路结合 api_client.dart 的invokeAPI与各 API 方法一次调用的完整链路为调用方创建 API 实例默认复用defaultApiClientAPI 方法校验必填参数替换路径占位符按 collectionFormat 组装查询参数并声明contentTypes与authNamesinvokeAPI依据authNames应用鉴权写入 header 或 query拼接basePath path queryString合并默认头与Content-Type根据contentType分流multipart/form-data走MultipartRequest如uploadFileapplication/x-www-form-urlencoded使用formParams如updatePetWithForm其余情况将 body 序列化为 JSON按 HTTP 方法分发到post/put/delete/patch/get响应码 400抛ApiException否则按声明的返回类型如Pet、ListPet反序列化后返回。作者信息示例服务与生成包的维护联系邮箱为apiteamswagger.io相关贡献与使用约定可参考仓库根目录的 README.md 与 CONTRIBUTING.md。小结本文以 Swagger Codegen 仓库中的 Dart Petstore 示例包为线索串联了“生成产物结构 → 环境与依赖配置 → 示例调用 → API/模型/鉴权清单 → 生成器与运行时源码实现”的完整链路。对开发者而言可直接复用文中的 pubspec 接入方式与调用模板对希望二次定制生成器的工程师而言DartClientCodegen.java 的 CLI 参数、类型映射与模板装配逻辑是最佳切入点。赞分享开发工具代码生成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 / Flutter 客户端实战以 swagger-codegen Petstore 包为例的安装、认证与 API 调用指南Swagger Codegen 生成 Dart / Flutter 客户端实战以 swagger codegen Petstore 包为例的安装、认证与 AP开发工具代码生成API设计使用 Swagger Codegen 生成 Dart Jaguar 客户端Petstore 示例包完整解读使用 Swagger Codegen 生成 Dart Jaguar 客户端Petstore 示例包完整解读 本文以 Swagger Codegen 仓库中 s开发工具代码生成API设计Swagger Codegen 生成 Dart Flutter PetApi 客户端使用完全指南以 Petstore 为例Swagger Codegen 生成 Dart Flutter PetApi 客户端使用完全指南以 Petstore 为例 本文档是 Swagger Code开发工具代码生成API设计创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考