Swagger Codegen Java 客户端 StoreApi 实战：okhttp4-gson Parcelable 生成代码的 Store 端点完全指南

• 开发工具
• 代码生成
• API设计

本篇指南以 swagger-codegen 仓库中自动生成的 Java（okhttp4-gson-parcelableModel 库型）Petstore 客户端为例，完整讲解StoreApi的 4 个 Store 业务端点——下单、查询订单、删除订单、查询库存——的调用方式、参数约定、认证配置与底层生成代码结构。读完本文，你将掌握基于 OkHttp4 + Gson + Parcelable 的生成式 API 客户端的标准用法，并能从源码层面理解每个端点背后的同步 / 异步 / HTTP 细节调用链。

概览：StoreApi 是什么

在 swagger-codegen 的 Java 客户端样例中，StoreApi是围绕 Petstore 的 "Store"（商店/订单）领域生成的 API 门面类，对应 OpenAPI 规范里store标签下的全部操作。本样例的完整文档位于 samples/client/petstore/java/okhttp4-gson-parcelableModel/docs/StoreApi.md，对应的规范来源是 fixtures/immutable/specifications/v3/petstore3fake.yaml 中的/store/inventory、/store/order、/store/order/{order_id}三组路径定义。

所有 URI 均相对于http://petstore.swagger.io:80/v2（即ApiClient的默认basePath）。StoreApi共暴露 4 个方法：

对应的生成类文件为 StoreApi.java，测试脚手架为 StoreApiTest.java。

准备工作：构建与引入客户端

在调用StoreApi之前，先通过样例根目录的 README.md 完成库的构建与引入。

环境要求：Java 1.7+，构建工具 Maven 或 Gradle。

安装到本地 Maven 仓库：

mvn clean install

部署到远程仓库（需先配置仓库 settings）：

mvn clean deploy

Maven 用户在项目 POM 中加入依赖：

<dependency> <groupId>io.swagger</groupId> <artifactId>swagger-petstore-okhttp4-gson</artifactId> <version>1.0.0</version> <scope>compile</scope> </dependency>

Gradle 用户在 build 文件中加入：

compile "io.swagger:swagger-petstore-okhttp4-gson:1.0.0"

手动安装 JAR（不使用仓库时）：

mvn clean package

随后手动安装target/swagger-petstore-okhttp4-gson-1.0.0.jar与target/lib/*.jar。

创建 API 实例有两种方式：无参构造new StoreApi()会使用Configuration.getDefaultApiClient()的全局默认客户端；也可传入自定义的ApiClient。若目标服务地址与默认的http://petstore.swagger.io:80/v2不同，可通过 ApiClient.setBasePath 修改，例如：

ApiClient apiClient = Configuration.getDefaultApiClient(); apiClient.setBasePath("http://your-host:8080/v2"); StoreApi apiInstance = new StoreApi(apiClient);

deleteOrder：按 ID 删除订单

端点：DELETE /store/order/{order_id}，用于删除指定 ID 的购买订单。规范描述提示：有效响应应使用小于 1000 的整数 ID，任何超过 1000 或非整数的 ID 都会产生 API 错误（见 petstore3fake.yaml 中deleteOrder的order_id参数定义为type: string，响应包含 400 Invalid ID supplied 与 404 Order not found）。

Java 示例：

// 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(); }

参数：

返回类型：null（空响应体）。对应源码中deleteOrder的返回是void，内部走ApiResponse<Void>（StoreApi.java）。

认证：无需授权。

HTTP 请求头：

• Content-Type：未定义
• Accept：application/xml, application/json

源码调用链：deleteOrder(orderId)→deleteOrderWithHttpInfo(orderId)→deleteOrderValidateBeforeCall（校验必填参数，若orderId == null抛出ApiException("Missing the required parameter 'orderId' when calling deleteOrder(Async)")）→deleteOrderCall（构造路径时通过apiClient.escapeString(orderId.toString())将{order_id}占位符替换并做 URL 转义）→apiClient.execute(call)。

getInventory：按状态查询宠物库存

端点：GET /store/inventory，返回一个"状态码 → 数量"的映射。它是 4 个端点中唯一需要认证的接口。规范中该路径的响应 schema 为type: object, additionalProperties: type: integer, format: int32，且声明了security: api_key（petstore3fake.yaml）。

Java 示例：

// 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 { Map<String, Integer> result = apiInstance.getInventory(); System.out.println(result); } catch (ApiException e) { System.err.println("Exception when calling StoreApi#getInventory"); e.printStackTrace(); }

参数：本端点无任何参数。

返回类型：Map<String, Integer>。

认证：api_key（即 README.md 中定义的 API key 认证：参数名api_key，位于 HTTP header）。

HTTP 请求头：

• Content-Type：未定义
• Accept：application/json

源码调用链与底层原理：getInventory()→getInventoryWithHttpInfo()，返回类型通过 Gson 的new TypeToken<Map<String, Integer>>(){}.getType()解析（StoreApi.java）。认证方面，生成代码在getInventoryCall中注入了String[] localVarAuthNames = new String[] { "api_key" }，由ApiClient.buildCall调用认证器的applyToParams。API key 的注入逻辑见 ApiKeyAuth.java：设置apiKey后，若同时设置了apiKeyPrefix，实际发送值为apiKeyPrefix + " " + apiKey（例如Token xxx），否则直接发送apiKey；对 header 型认证写入headerParams.put(paramName, value)。

getOrderById：按 ID 查询订单

端点：GET /store/order/{order_id}。规范描述提示：有效响应应使用<= 5或> 10的整数 ID，其他值会产生异常；同时该参数在规范中带有maximum: 5, minimum: 1, type: integer, format: int64约束（petstore3fake.yaml），因此 Java 端类型为Long。

Java 示例：

// Import classes: //import io.swagger.client.ApiException; //importimport 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(); }

参数：

返回类型：Order。

认证：无需授权。

HTTP 请求头：

• Content-Type：未定义
• Accept：application/xml, application/json

源码调用链：与deleteOrder相同的三阶段模式——getOrderById(orderId)先经getOrderByIdValidateBeforeCall校验orderId非空，再由getOrderByIdCall完成路径占位符替换与Accept头选择（selectHeaderAccept从{"application/xml", "application/json"}中挑选），最后execute使用TypeToken<Order>反序列化响应体（StoreApi.java）。

placeOrder：为宠物下单

端点：POST /store/order，请求体为Order对象（规范中requestBody的 schema$ref: '#/components/schemas/Order'且required: true，响应 200 返回 Order，400 表示 Invalid Order，见 petstore3fake.yaml）。

Java 示例：

// 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(); }

参数：

返回类型：Order。

认证：无需授权。

HTTP 请求头：

• Content-Type：未定义
• Accept：application/xml, application/json

源码调用链：placeOrder(body)→placeOrderValidateBeforeCall（校验body == null时抛异常）→placeOrderCall（localVarPostBody = body作为请求体传入buildCall，方法POST）→execute(call, TypeToken<Order>)（StoreApi.java）。

Order 模型与 Parcelable 特性：本样例的库型为okhttp4-gson-parcelableModel，因此 Order.java 实现了android.os.Parcelable，包含字段id（Long）、petId（Long）、quantity（Integer）、shipDate（org.threeten.bp.OffsetDateTime）、status（枚举StatusEnum：placed/approved/delivered，通过 Gson 自定义TypeAdapter做 JSON 序列化）、complete（Boolean，默认false），并配套writeToParcel/CREATOR，方便在 Android 组件（如 Intent、Bundle）间传递订单对象。

异步调用与进度监听

生成代码为每个端点额外提供了异步变体与"带 HTTP 信息"的变体，这在文档示例之外属于源码层面的增强能力（可依据 StoreApi.java 验证）：

• xxxWithHttpInfo(...)：返回ApiResponse<T>，可拿到完整 HTTP 状态码、响应头与响应体。
• xxxAsync(..., ApiCallback<T> callback)：基于 OkHttp 的异步执行，回调接口ApiCallback包含onFailure、onSuccess、onUploadProgress、onDownloadProgress；生成代码通过 OkHttp 的networkInterceptors()注册ProgressResponseBody/ProgressRequestBody实现上下行进度回调（见 ProgressRequestBody.java 与 ProgressResponseBody.java）。

例如异步查询订单：

apiInstance.getOrderByIdAsync(789L, new ApiCallback<Order>() { @Override public void onFailure(ApiException e, int statusCode, Map<String, List<String>> responseHeaders) { e.printStackTrace(); } @Override public void onSuccess(Order result, int statusCode, Map<String, List<String>> responseHeaders) { System.out.println(result); } @Override public void onUploadProgress(long bytesWritten, long contentLength, boolean done) { } @Override public void onDownloadProgress(long bytesRead, long contentLength, boolean done) { } });

测试与验证

样例提供了 JUnit 测试脚手架 StoreApiTest.java（类级标注@Ignore，默认不执行真实网络调用），为 4 个端点各生成一个@Test方法：deleteOrderTest、getInventoryTest、getOrderByIdTest、placeOrderTest。将其中的null参数替换为真实值并去掉@Ignore，即可对实际部署的 Petstore 服务做端到端验证；这也说明生成代码的"文档—源码—测试"三者一一对应，是学习 swagger-codegen 输出结构的良好范本。

小结

StoreApi的 4 个端点覆盖了 Store 领域最典型的 CRUD 场景：带路径参数的无返回体操作（deleteOrder）、需要 API key 认证的无参查询（getInventory）、路径参数 + 模型返回（getOrderById）以及请求体 + 模型返回（placeOrder）。从源码结构看，swagger-codegen 为每个操作生成Call 构建 → 参数校验 → 同步/异步/WithHttpInfo的规整分层，配合 OkHttp4 的拦截器机制、Gson 的类型反序列化与 Parcelable 的 Android 传输支持，让开发者无需手写 HTTP 细节即可安全、高效地接入 OpenAPI 定义的后端服务。

• 开发工具
• 代码生成
• API设计