ARTICLE DETAIL

资讯详情

深耕网站建设与运营推广的一线实战洞察。

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

Swagger Codegen Java 客户端 StoreApi 实战:okhttp4-gson Parcelable 生成代码的 Store 端点完全指南 开发工具代码生成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 仓库中自动生成的 Javaokhttp4-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 个方法方法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对应的生成类文件为 StoreApi.java测试脚手架为 StoreApiTest.java。准备工作构建与引入客户端在调用StoreApi之前先通过样例根目录的 README.md 完成库的构建与引入。环境要求Java 1.7构建工具 Maven 或 Gradle。安装到本地 Maven 仓库mvn clean install部署到远程仓库需先配置仓库 settingsmvn clean deployMaven 用户在项目 POM 中加入依赖dependency groupIdio.swagger/groupId artifactIdswagger-petstore-okhttp4-gson/artifactId version1.0.0/version scopecompile/scope /dependencyGradle 用户在 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(); }参数NameTypeDescriptionNotesorderIdStringID of the order that needs to be deleted返回类型null空响应体。对应源码中deleteOrder的返回是void内部走ApiResponseVoidStoreApi.java。认证无需授权。HTTP 请求头Content-Type未定义Acceptapplication/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_keypetstore3fake.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 { 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_key即 README.md 中定义的 API key 认证参数名api_key位于 HTTP header。HTTP 请求头Content-Type未定义Acceptapplication/json源码调用链与底层原理getInventory()→getInventoryWithHttpInfo()返回类型通过 Gson 的new TypeTokenMapString, 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(); }参数NameTypeDescriptionNotesorderIdLongID of pet that needs to be fetched返回类型Order。认证无需授权。HTTP 请求头Content-Type未定义Acceptapplication/xml, application/json源码调用链与deleteOrder相同的三阶段模式——getOrderById(orderId)先经getOrderByIdValidateBeforeCall校验orderId非空再由getOrderByIdCall完成路径占位符替换与Accept头选择selectHeaderAccept从{application/xml, application/json}中挑选最后execute使用TypeTokenOrder反序列化响应体StoreApi.java。placeOrder为宠物下单端点POST /store/order请求体为Order对象规范中requestBody的 schema$ref: #/components/schemas/Order且required: true响应 200 返回 Order400 表示 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(); }参数NameTypeDescriptionNotesbodyOrderorder placed for purchasing the pet返回类型Order。认证无需授权。HTTP 请求头Content-Type未定义Acceptapplication/xml, application/json源码调用链placeOrder(body)→placeOrderValidateBeforeCall校验body null时抛异常→placeOrderCalllocalVarPostBody body作为请求体传入buildCall方法POST→execute(call, TypeTokenOrder)StoreApi.java。Order 模型与 Parcelable 特性本样例的库型为okhttp4-gson-parcelableModel因此 Order.java 实现了android.os.Parcelable包含字段idLong、petIdLong、quantityInteger、shipDateorg.threeten.bp.OffsetDateTime、status枚举StatusEnumplaced/approved/delivered通过 Gson 自定义TypeAdapter做 JSON 序列化、completeBoolean默认false并配套writeToParcel/CREATOR方便在 Android 组件如 Intent、Bundle间传递订单对象。异步调用与进度监听生成代码为每个端点额外提供了异步变体与带 HTTP 信息的变体这在文档示例之外属于源码层面的增强能力可依据 StoreApi.java 验证xxxWithHttpInfo(...)返回ApiResponseT可拿到完整 HTTP 状态码、响应头与响应体。xxxAsync(..., ApiCallbackT callback)基于 OkHttp 的异步执行回调接口ApiCallback包含onFailure、onSuccess、onUploadProgress、onDownloadProgress生成代码通过 OkHttp 的networkInterceptors()注册ProgressResponseBody/ProgressRequestBody实现上下行进度回调见 ProgressRequestBody.java 与 ProgressResponseBody.java。例如异步查询订单apiInstance.getOrderByIdAsync(789L, new ApiCallbackOrder() { Override public void onFailure(ApiException e, int statusCode, MapString, ListString responseHeaders) { e.printStackTrace(); } Override public void onSuccess(Order result, int statusCode, MapString, ListString 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设计【免费下载链接】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点击查看免费下载相关推荐Anthropic-Cybersecurity-Skills 实战指南MS17-010 EternalBlue 漏洞检测、利用与评估报告生成Anthropic Cybersecurity Skills 实战指南MS17 010 EternalBlue 漏洞检测、利用与评估报告生成 导读 本文基于开发工具代码生成API设计Qwen Code CLI 的 Usage-only 流内存治理从无界增长到常量级保留的设计与实现Qwen Code CLI 的 Usage only 流内存治理从无界增长到常量级保留的设计与实现 导读 本文围绕 Qwen Code终端内开源 AI 编码开发工具代码生成API设计Swagger Codegen 生成的 Java okhttp4-gson 客户端 FakeApi 实战指南十个 /fake 测试端点全解析Swagger Codegen 生成的 Java okhttp4 gson 客户端 FakeApi 实战指南十个 /fake 测试端点全解析 导读 Fake开发工具代码生成API设计上一篇排错实战google-oauth-java-client 高频异常 Top 7 与解决方案含 TokenResponseException下一篇Zoom Apps 架构深度解析构建运行于 Zoom 客户端内的 Web 应用knowledge-work-plugins 实战指南创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考
返回列表