swagger-codegen 生成的 Java okhttp-gson 客户端 StoreApi 实战指南：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点击查看免费下载StoreApi 是 swagger-codegen 基于 OpenAPI / Swagger 定义自动生成的 Java 客户端 API 类封装了 Swagger Petstore 的/store资源下全部 4 个接口删除订单、查询库存、按 ID 查订单、下单。本文以okhttp-gson-parcelableModel生成样例为对象完整讲解每个方法的参数、返回类型、认证方式与调用示例并深入对应源码说明请求的构建、校验、执行与异步回调机制帮助读者在阅读自动生成代码时快速定位方法、理解底层实现并正确接入自己的项目。文档定位与适用场景本文基于 swagger-codegen 仓库中的生成样例 samples/client/petstore/java/okhttp-gson-parcelableModel 展开。该目录是使用java语言生成器、以 OkHttp 2.x 作为 HTTP 客户端、Gson 作为 JSON 序列化库、并额外启用 Android Parcelable 支持的完整 Java 客户端工程所有文件均标注Automatically generated by the Swagger Codegen属于生成器输出产物。其中 API 文档 docs/StoreApi.md 列出了 StoreApi 的全部端点对应实现位于 src/main/java/io/swagger/client/api/StoreApi.java配套单元测试位于 src/test/java/io/swagger/client/api/StoreApiTest.java。StoreApi 端点总览文档开头给出所有 URIs 相对http://petstore.swagger.io:80/v2四个方法如下方法HTTP 请求描述deleteOrderDELETE/store/order/{order_id}Delete purchase order by IDgetInventoryGET/store/inventoryReturns pet inventories by statusgetOrderByIdGET/store/order/{order_id}Find purchase order by IDplaceOrderPOST/store/orderPlace an order for a pet其中deleteOrder与getOrderById共享同一路径模板/store/order/{order_id}前者删除、后者查询getInventory无需参数placeOrder以Order对象作为请求体。这一端点结构源自 Petstore 的 Swagger 定义见 samples/yaml/store.yml 中的resourcePath: /store生成器将路径模板中的{orderId}转换为代码中的{order_id}并映射为方法的路径参数。工程准备依赖与构建在调用 StoreApi 之前需要先把生成的客户端构建为 JAR 并引入依赖。按 README.md 的说明构建要求Java 1.7与 Maven / Gradle。安装到本地 Maven 仓库mvn clean install部署到远程仓库mvn clean deploy仅生成 JAR 则可执行mvn clean package然后手动安装target/swagger-petstore-okhttp-gson-1.0.0.jar与target/lib/*.jar。Maven 依赖坐标groupId/artifactId 来自 pom.xmldependency groupIdio.swagger/groupId artifactIdswagger-petstore-okhttp-gson/artifactId version1.0.0/version scopecompile/scope /dependencyGradle 用户等价写法compile io.swagger:swagger-petstore-okhttp-gson:1.0.0从 pom.xml 可以确认运行时依赖栈com.squareup.okhttp:okhttp:2.7.5负责 HTTP 传输com.google.code.gson:gson:2.8.1与io.gsonfire:gson-fire:1.8.3负责 JSON 序列化org.threeten:threetenbp:1.4.1提供OffsetDateTime等 Java 8 时间类型在 Java 7 环境下的支持而com.google.android:android:4.1.1.4以providedscope 引入专为 Parcelable 模型提供 Android 平台 API——这也是本样例目录名中parcelableModel的由来。环境初始化与认证配置所有 StoreApi 方法都通过ApiClient发送请求。ApiClient.java 的构造函数完成默认初始化默认basePath http://petstore.swagger.io:80/v2可通过setBasePath(String)修改默认 User-Agent 为Swagger-Codegen/1.0.0/java预注册四种认证方案api_keyheader 中的 API key、api_key_queryquery 中的 API key、http_basic_testHTTP Basic、petstore_authOAuth注册后以不可变 Map 保存。StoreApi的默认构造器直接复用全局单例见 StoreApi.javapublic StoreApi() { this(Configuration.getDefaultApiClient()); } public StoreApi(ApiClient apiClient) { this.apiClient apiClient; }因此在多线程环境下README 建议为每个线程创建独立的ApiClient实例以避免潜在问题如需更换服务地址或自定义超时可先构造自定义ApiClient再传入new StoreApi(apiClient)。deleteOrder按 ID 删除订单签名与描述public void deleteOrder(String orderId) throws ApiExceptionHTTP 请求为DELETE /store/order/{order_id}。文档特别提示有效的响应仅针对数值小于 1000 的整数 ID大于 1000 或非整数的值将产生 API 错误。调用示例// Import classes: //import io.swagger.client.ApiException; //import io.swagger.client.api.StoreApi; StoreApi apiInstance new StoreApi(); String orderId orderId_example; // String | ID of the order that needs to be deleted try { apiInstance.deleteOrder(orderId); } catch (ApiException e) { System.err.println(Exception when calling StoreApi#deleteOrder); e.printStackTrace(); }参数表NameTypeDescriptionNotesorderIdStringID of the order that needs to be deleted返回类型、授权与请求头返回类型null空响应体——删除操作无返回内容授权无需认证Content-Type未定义Acceptapplication/xml, application/json。源码实现要点在 StoreApi.java 中deleteOrderCall首先将路径模板做占位符替换String localVarPath /store/order/{order_id} .replaceAll(\\{ order_id \\}, apiClient.escapeString(orderId.toString()));escapeString负责 URL 编码避免路径参数中的特殊字符破坏 URL 结构。随后deleteOrderValidateBeforeCall会先校验必填参数orderId为null时抛出ApiException(Missing the required parameter orderId when calling deleteOrder(Async))见 StoreApi.java。最终deleteOrder通过deleteOrderWithHttpInfo→apiClient.execute(call)完成同步调用。getInventory按状态返回库存签名与描述public MapString, Integer getInventory() throws ApiExceptionHTTP 请求为GET /store/inventory返回状态码到数量的映射a map of status codes to quantities。文档明确本端点不需要任何参数。调用示例含 api_key 认证配置// Import classes: //import io.swagger.client.ApiClient; //import io.swagger.client.ApiException; //import io.swagger.client.Configuration; //import io.swagger.client.auth.*; //import io.swagger.client.api.StoreApi; ApiClient defaultClient Configuration.getDefaultApiClient(); // Configure API key authorization: api_key ApiKeyAuth api_key (ApiKeyAuth) defaultClient.getAuthentication(api_key); api_key.setApiKey(YOUR API KEY); // Uncomment the following line to set a prefix for the API key, e.g. Token (defaults to null) //api_key.setApiKeyPrefix(Token); StoreApi apiInstance new StoreApi(); try { MapString, Integer result apiInstance.getInventory(); System.out.println(result); } catch (ApiException e) { System.err.println(Exception when calling StoreApi#getInventory); e.printStackTrace(); }返回类型、授权与请求头返回类型MapString, Integer授权api_keyContent-Type未定义Acceptapplication/json与其他三个端点不同该接口不接受 XML 响应。源码实现要点getInventoryCall中声明的认证名称为api_key见 StoreApi.java这解释了为什么该端点示例代码必须配置 API key。认证的实现类 ApiKeyAuth.java 在applyToParams中拼接 key 值若设置了apiKeyPrefix实际发送值为prefix apiKey否则仅发送 key 本身location为header时写入请求头本仓库配置为参数名api_key放在 HTTP header为query时追加到查询参数。响应反序列化使用 Gson 的TypeTokenMapString, Integer(){}获取泛型类型见 StoreApi.java。getOrderById按 ID 查询订单签名与描述public Order getOrderById(Long orderId) throws ApiExceptionHTTP 请求为GET /store/order/{order_id}。文档提示有效的响应针对数值 ≤ 5 或 10 的整数 ID其他值将生成异常来自 Swagger 定义的测试约束见 samples/yaml/store.yml。调用示例// Import classes: //import io.swagger.client.ApiException; //import io.swagger.client.api.StoreApi; StoreApi apiInstance new StoreApi(); Long orderId 789L; // Long | ID of pet that needs to be fetched try { Order result apiInstance.getOrderById(orderId); System.out.println(result); } catch (ApiException e) { System.err.println(Exception when calling StoreApi#getOrderById); e.printStackTrace(); }参数表NameTypeDescriptionNotesorderIdLongID of pet that needs to be fetched注意deleteOrder的路径参数是String而getOrderById的是Long二者虽共用路径模板参数类型却由 Swagger 定义中的类型stringvsinteger/int64分别决定这也体现了生成器按定义逐端点生成签名的方式。返回类型、授权与请求头返回类型Order授权无需认证Content-Type未定义Acceptapplication/xml, application/json。源码实现要点与deleteOrder相同的“构建调用 → 校验参数 → 执行”三步结构getOrderByIdCall替换路径占位符StoreApi.javagetOrderByIdValidateBeforeCall对orderId做 null 校验最终通过apiClient.execute(call, new TypeTokenOrder(){}.getType())将响应体反序列化为Order模型StoreApi.java。placeOrder为宠物下单签名与描述public Order placeOrder(Order body) throws ApiExceptionHTTP 请求为POST /store/order请求体为Order对象order placed for purchasing the pet。调用示例// Import classes: //import io.swagger.client.ApiException; //import io.swagger.client.api.StoreApi; StoreApi apiInstance new StoreApi(); Order body new Order(); // Order | order placed for purchasing the pet try { Order result apiInstance.placeOrder(body); System.out.println(result); } catch (ApiException e) { System.err.println(Exception when calling StoreApi#placeOrder); e.printStackTrace(); }参数表NameTypeDescriptionNotesbodyOrderorder placed for purchasing the pet返回类型、授权与请求头返回类型Order授权无需认证Content-Type未定义Acceptapplication/xml, application/json。源码实现要点placeOrderCall将body直接赋给localVarPostBodyStoreApi.java由ApiClient在buildCall阶段通过 Gson 序列化为请求体并设置 Content-Type校验逻辑同样要求body非空StoreApi.java。Order 模型与 Parcelable 特性placeOrder的请求体与getOrderById的返回值都是Order。按 docs/Order.md 的属性表NameTypeDescriptionNotesidLong[optional]petIdLong[optional]quantityInteger[optional]shipDateOffsetDateTime[optional]statusStatusEnumOrder Status[optional]completeBoolean[optional]其中status为枚举StatusEnumPLACED(placed)、APPROVED(approved)、DELIVERED(delivered)对应 samples/yaml/store.yml 定义中的枚举值。在实现 Order.java 中该类实现了Parcelable接口字段以SerializedName注解与 JSON 字段映射status枚举通过 Gson 的TypeAdapter自定义序列化同时提供writeToParcel/CREATOR.createFromParcel完成 Android Parcel 的写入与恢复。这是该样例与普通 okhttp-gson 客户端的核心差异——生成的模型可直接在 Android Activity / Fragment 之间以 Intent Bundle 或 Parcelable 形式传递。统一请求链路同步、带元信息与异步调用观察 StoreApi.java 可发现每个端点都生成三组方法对应三种调用方式同步简洁版deleteOrder(orderId)、getOrderById(orderId)、placeOrder(body)等直接返回数据或void带 HTTP 元信息版deleteOrderWithHttpInfo(orderId)返回ApiResponseVoidgetOrderByIdWithHttpInfo返回ApiResponseOrder可同时获得状态码与响应头异步回调版deleteOrderAsync(orderId, callback)、getOrderByIdAsync(orderId, callback)、placeOrderAsync(body, callback)等返回com.squareup.okhttp.Call通过ApiCallbackT回调处理成功、失败与上传/下载进度。异步版本的底层在回调存在时将进度监听包装为ProgressRequestBody.ProgressRequestListener与ProgressResponseBody.ProgressListener注入 OkHttp 的 network interceptor 后调用apiClient.executeAsync(...)见 StoreApi.java。因此无论采用哪种调用方式最终都会收敛到ApiClient.buildCall(...)构建okhttp.Call再由execute/executeAsync执行——这也是所有生成 API 类共享的统一请求链路。测试验证配套的 StoreApiTest.java 为每个端点生成了 JUnit 测试骨架类标注Ignore需要真实服务时移除注解并填充参数deleteOrderTest调用api.deleteOrder(orderId)getInventoryTest断言返回MapString, Integer response api.getInventory()getOrderByIdTest断言返回Order response api.getOrderById(orderId)placeOrderTest断言返回Order response api.placeOrder(body)。这些测试与文档、源码三者一一对应可用于快速验证客户端与 Petstore 测试服务器的联通性也可作为接入自有后端时的修改起点。小结StoreApi 的四个方法完整覆盖了 Petstore/store资源deleteOrder与getOrderById演示了路径参数String 与 Long与占位符转义getInventory演示了 API key 认证与泛型 Map 响应placeOrder演示了模型请求体与枚举字段的序列化。通过对 docs/StoreApi.md 与 StoreApi.java 的对照阅读读者既能获得可直接运行的调用代码也能理解生成器“定义 → 文档 → 实现 → 测试”四者一致的输出模式从而在自己项目中熟练使用由 swagger-codegen 生成的任何 API 客户端。赞分享开发工具代码生成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 Bash 客户端 StoreApi 实战指南用 petstore-cli 调用 Petstore 订单与库存接口Swagger Codegen Bash 客户端 StoreApi 实战指南用 petstore cli 调用 Petstore 订单与库存接口 导读 本指南开发工具代码生成API设计swagger-codegen 生成的 C 客户端 StoreApi 使用指南Petstore 订单与库存接口全解析swagger codegen 生成的 C 客户端 StoreApi 使用指南Petstore 订单与库存接口全解析 导读 本篇技术指南聚焦 swagger开发工具代码生成API设计Swagger Codegen 生成的 Dart Flutter Petstore StoreApi 使用指南订单与库存接口实战Swagger Codegen 生成的 Dart Flutter Petstore StoreApi 使用指南订单与库存接口实战 导读 StoreApi 是开发工具代码生成API设计上一篇开源智能电池管理系统SmartBMS从零搭建专业锂电池保护方案下一篇Unity Native Camera终极跨平台相机集成解决方案创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考