swagger-codegen 生成 Java 客户端 FakeApi 全端点实战指南：okhttp4-gson-parcelableModel 版本解析与调用

开发工具代码生成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 仓库中生成的 Java 客户端示例okhttp4-gson-parcelableModel为对象系统讲解其FakeApi的 10 个测试端点从方法签名、HTTP 路由、请求/响应类型到认证方式与底层实现。读完本文你将掌握如何在 AndroidParcelable环境下使用 okhttp4 Gson 栈调用 Swagger Petstore 的 fake 端点并理解 swagger-codegen 模板引擎为每个端点生成的同步调用 带 HttpInfo 调用 异步回调调用三套方法背后的完整调用链。一、文档与产物定位FakeApi 在生成客户端中的角色FakeApi.md是 swagger-codegen 针对 Swagger Petstore 规范自动生成的 API 参考文档之一位于 samples/client/petstore/java/okhttp4-gson-parcelableModel/docs/FakeApi.md。它对应的运行时实现是 FakeApi.java由模板引擎依据 OpenAPI/Swagger 定义中tag: fake的一组操作批量产出。该示例包名为swagger-petstore-okhttp4-gson见 pom.xml技术栈特征明显okhttp 4.10.0HTTP 客户端com.squareup.okhttp3:okhttp与logging-interceptorGson 2.10.1 gson-fire 1.8.5JSON 序列化/反序列化threetenbp 1.6.5LocalDate、OffsetDateTime等日期时间类型com.google.android:android 4.1.1.4provided 作用域为模型类提供android.os.Parcelable支持——这正是parcelableModel后缀的由来例如 OuterComposite.java 实现了Parcelable接口并生成writeToParcel/CREATOR代码便于在 Android 进程间传递模型对象Java 1.7、Maven/Gradle构建见 README.md。注意Petstore 规范的描述明确说明此规范主要用于测试 Petstore 服务器包含 fake 端点与模型请勿用于其他用途因此 FakeApi 的端点全部是功能性测试端点用于验证 swagger-codegen 对各类参数形态的生成能力。二、端点总览方法、HTTP 请求与说明FakeApi 全部端点均相对于基准地址http://petstore.swagger.io:80/v2文档中给出的方法表如下MethodHTTP requestDescriptionfakeOuterBooleanSerializePOST/fake/outer/booleanfakeOuterCompositeSerializePOST/fake/outer/compositefakeOuterNumberSerializePOST/fake/outer/numberfakeOuterStringSerializePOST/fake/outer/stringtestBodyWithQueryParamsPUT/fake/body-with-query-paramstestClientModelPATCH/fakeTo test client modeltestEndpointParametersPOST/fakeFake endpoint for testing various parameters 假端點 偽のエンドポイント 가짜 엔드 포인트testEnumParametersGET/fakeTo test enum parameterstestInlineAdditionalPropertiesPOST/fake/inline-additionalPropertiestest inline additionalPropertiestestJsonFormDataGET/fake/jsonFormDatatest json serialization of form data从源码 FakeApi.java 中可以确认这 10 个端点分别映射到 4 个 HTTP 方法POST/PUT/PATCH/GET且每个方法在生成的类中都存在三种形态同步方法如fakeOuterBooleanSerialize(Boolean body)返回业务类型或voidWithHttpInfo方法如fakeOuterBooleanSerializeWithHttpInfo(...)返回ApiResponseT携带 HTTP 状态码与响应头Async方法如fakeOuterBooleanSerializeAsync(..., ApiCallbackT callback)返回okhttp3.Call通过回调处理结果。这三套方法共用底层的xxxCall(...)构建请求与xxxValidateBeforeCall(...)校验必填参数是 swagger-codegen Java 模板的标准输出结构。三、外层类型序列化端点fakeOuter* 系列四个fakeOuter*端点专门测试外层类型outer types的序列化——即 Swagger 定义中直接作为请求体/响应体的标量类型Boolean、BigDecimal、String以及组合对象OuterComposite。它们全部使用 POST 方法、无认证、Content-Type 与 Accept 均为Not defined生成代码中对应的localVarAccepts与localVarContentTypes数组为空apiClient.selectHeaderAccept/selectHeaderContentType返回空并仅回填默认头。1. fakeOuterBooleanSerialize测试外层布尔类型的序列化请求体为布尔值响应体为布尔值。// Import classes: //import io.swagger.client.ApiException; //import io.swagger.client.api.FakeApi; FakeApi apiInstance new FakeApi(); Boolean body true; // Boolean | Input boolean as post body try { Boolean result apiInstance.fakeOuterBooleanSerialize(body); System.out.println(result); } catch (ApiException e) { System.err.println(Exception when calling FakeApi#fakeOuterBooleanSerialize); e.printStackTrace(); }参数body类型Boolean描述为 Input boolean as post body可选[optional]。返回类型Boolean。源码中通过TypeTokenBoolean{}.getType()指定反序列化目标FakeApi.java。2. fakeOuterCompositeSerialize测试包含外层数字类型的对象序列化请求体为OuterComposite对象响应体同为OuterComposite。FakeApi apiInstance new FakeApi(); OuterComposite body new OuterComposite(); // OuterComposite | Input composite as post body try { OuterComposite result apiInstance.fakeOuterCompositeSerialize(body); System.out.println(result); } catch (ApiException e) { System.err.println(Exception when calling FakeApi#fakeOuterCompositeSerialize); e.printStackTrace(); }参数body类型OuterCompositeInput composite as post body可选。返回类型OuterComposite。OuterComposite模型OuterComposite.java包含三个字段myNumberBigDecimalJSON 键my_number、myStringString键my_string、myBooleanBoolean键my_boolean并提供链式 setter、equals/hashCode/toString以及 Parcelable 的writeToParcel/CREATOR实现。3. fakeOuterNumberSerialize测试外层数字类型的序列化请求体与响应体均为BigDecimal。FakeApi apiInstance new FakeApi(); BigDecimal body new BigDecimal(); // BigDecimal | Input number as post body try { BigDecimal result apiInstance.fakeOuterNumberSerialize(body); System.out.println(result); } catch (ApiException e) { System.err.println(Exception when calling FakeApi#fakeOuterNumberSerialize); e.printStackTrace(); }参数body类型BigDecimal可选。返回类型BigDecimal。4. fakeOuterStringSerialize测试外层字符串类型的序列化请求体与响应体均为String。FakeApi apiInstance new FakeApi(); String body body_example; // String | Input string as post body try { String result apiInstance.fakeOuterStringSerialize(body); System.out.println(result); } catch (ApiException e) { System.err.println(Exception when calling FakeApi#fakeOuterStringSerialize); e.printStackTrace(); }参数body类型String可选。返回类型String。四、请求体与查询参数组合testBodyWithQueryParams该端点用于测试请求体 查询参数同时存在的场景使用PUT方法访问/fake/body-with-query-params。两个参数均为必填源码的ValidateBeforeCall阶段会显式校验body或query为null时抛出ApiException(Missing the required parameter ...)FakeApi.java。FakeApi apiInstance new FakeApi(); User body new User(); // User | String query query_example; // String | try { apiInstance.testBodyWithQueryParams(body, query); } catch (ApiException e) { System.err.println(Exception when calling FakeApi#testBodyWithQueryParams); e.printStackTrace(); }参数NameTypeDescriptionNotesbodyUser必填queryString必填返回类型null空响应体对应生成方法void testBodyWithQueryParams(User body, String query)。HTTP 请求头Content-Type 为application/jsonAccept 未定义。从源码看query被加入 query 参数列表apiClient.parameterToPair(query, query)而body作为localVarPostBody以 JSON 形式发送Content-Type 数组为{application/json}。五、模型回显测试testClientModel该端点使用PATCH方法访问/fake用于测试 client 模型——发送Client对象并期望原样返回。FakeApi apiInstance new FakeApi(); Client body new Client(); // Client | client model try { Client result apiInstance.testClientModel(body); System.out.println(result); } catch (ApiException e) { System.err.println(Exception when calling FakeApi#testClientModel); e.printStackTrace(); }参数body类型Clientclient model必填ValidateBeforeCall中同样做了非空校验。返回类型ClientClient.md。HTTP 请求头Content-Type 为application/jsonAccept 为application/json——请求与响应均为 JSON。六、参数形态最全的测试端点testEndpointParameters这是 FakeApi 中参数最多的端点使用POST方法访问/fake用于测试多种参数类型数值BigDecimal/Double/Float/Integer/Long、字符串含正则 pattern、字节数组byte[]、日期时间LocalDate/OffsetDateTime、密码与回调参数。其中number、_double、patternWithoutDelimiter、_byte为必填其余 10 个为可选。该端点同时演示了 HTTP Basic 认证http_basic_test与多值 Content-Type/Acceptapplication/xml; charsetutf-8、application/json; charsetutf-8。命名细节double、float、byte等是 Java 关键字生成器自动为参数名添加下划线前缀_double、_float、_byte而patternWithoutDelimiter对应表单键pattern_without_delimiterparamCallback对应表单键callback。// 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.FakeApi; ApiClient defaultClient Configuration.getDefaultApiClient(); // Configure HTTP basic authorization: http_basic_test HttpBasicAuth http_basic_test (HttpBasicAuth) defaultClient.getAuthentication(http_basic_test); http_basic_test.setUsername(YOUR USERNAME); http_basic_test.setPassword(YOUR PASSWORD); FakeApi apiInstance new FakeApi(); BigDecimal number new BigDecimal(); // BigDecimal | None Double _double 3.4D; // Double | None String patternWithoutDelimiter patternWithoutDelimiter_example; // String | None byte[] _byte B; // byte[] | None Integer integer 56; // Integer | None Integer int32 56; // Integer | None Long int64 789L; // Long | None Float _float 3.4F; // Float | None String string string_example; // String | None byte[] binary B; // byte[] | None LocalDate date LocalDate.now(); // LocalDate | None OffsetDateTime dateTime OffsetDateTime.now(); // OffsetDateTime | None String password password_example; // String | None String paramCallback paramCallback_example; // String | None try { apiInstance.testEndpointParameters(number, _double, patternWithoutDelimiter, _byte, integer, int32, int64, _float, string, binary, date, dateTime, password, paramCallback); } catch (ApiException e) { System.err.println(Exception when calling FakeApi#testEndpointParameters); e.printStackTrace(); }参数NameTypeDescriptionNotesnumberBigDecimalNone必填_doubleDoubleNone必填patternWithoutDelimiterStringNone必填_bytebyte[]None必填integerIntegerNone可选int32IntegerNone可选int64LongNone可选_floatFloatNone可选stringStringNone可选binarybyte[]None可选dateLocalDateNone可选dateTimeOffsetDateTimeNone可选passwordStringNone可选paramCallbackStringNone可选返回类型null空响应体。Authorizationhttp_basic_testHTTP Basic用户名/密码。HTTP 请求头Content-Type 为application/xml; charsetutf-8, application/json; charsetutf-8Accept 相同。源码实现中FakeApi.java该端点无请求体localVarPostBody null所有参数均放入localVarFormParams以表单形式提交认证名数组为{http_basic_test}由apiClient.buildCall统一处理 Basic 认证头。七、枚举参数端点testEnumParameters该端点使用GET方法访问/fake测试表单、Header、Query 三种位置的枚举参数覆盖字符串数组enum:、$、字符串enum:_abc、-efg、(xyz)默认-efg、整数enum:1、-2与浮点数enum:1.1、-1.2。此端点还验证了集合参数的 CSV 序列化与双精度参数以表单而非查询方式提交的生成行为。FakeApi apiInstance new FakeApi(); ListString enumFormStringArray Arrays.asList(enumFormStringArray_example); // ListString | Form parameter enum test (string array) String enumFormString -efg; // String | Form parameter enum test (string) ListString enumHeaderStringArray Arrays.asList(enumHeaderStringArray_example); // ListString | Header parameter enum test (string array) String enumHeaderString -efg; // String | Header parameter enum test (string) ListString enumQueryStringArray Arrays.asList(enumQueryStringArray_example); // ListString | Query parameter enum test (string array) String enumQueryString -efg; // String | Query parameter enum test (string) Integer enumQueryInteger 56; // Integer | Query parameter enum test (double) Double enumQueryDouble 3.4D; // Double | Query parameter enum test (double) try { apiInstance.testEnumParameters(enumFormStringArray, enumFormString, enumHeaderStringArray, enumHeaderString, enumQueryStringArray, enumQueryString, enumQueryInteger, enumQueryDouble); } catch (ApiException e) { System.err.println(Exception when calling FakeApi#testEnumParameters); e.printStackTrace(); }参数NameTypeDescriptionNotesenumFormStringArrayListStringForm parameter enum test (string array)可选 [enum: , $]enumFormStringStringForm parameter enum test (string)可选 [默认 -efg] [enum: _abc, -efg, (xyz)]enumHeaderStringArrayListStringHeader parameter enum test (string array)可选 [enum: , $]enumHeaderStringStringHeader parameter enum test (string)可选 [默认 -efg] [enum: _abc, -efg, (xyz)]enumQueryStringArrayListStringQuery parameter enum test (string array)可选 [enum: , $]enumQueryStringStringQuery parameter enum test (string)可选 [默认 -efg] [enum: _abc, -efg, (xyz)]enumQueryIntegerIntegerQuery parameter enum test (double)可选 [enum: 1, -2]enumQueryDoubleDoubleQuery parameter enum test (double)可选 [enum: 1.1, -1.2]返回类型null空响应体。HTTP 请求头Content-Type 为*/*Accept 为*/*。源码中的参数分派逻辑FakeApi.javaenumQueryStringArray走集合查询参数apiClient.parameterToPairs(csv, enum_query_string_array, ...)enumQueryString、enumQueryInteger走普通查询参数parameterToPairenumHeaderStringArray、enumHeaderString放入 Header 参数表enumFormStringArray、enumFormString、enumQueryDouble放入表单参数表注意enumQueryDouble虽以 query 命名但生成时归入 form。八、内联 additionalProperties 与 JSON 表单数据1. testInlineAdditionalProperties使用POST方法访问/fake/inline-additionalProperties测试内联additionalProperties即动态键值对请求体的序列化请求体类型为Object。FakeApi apiInstance new FakeApi(); Object param null; // Object | request body try { apiInstance.testInlineAdditionalProperties(param); } catch (ApiException e) { System.err.println(Exception when calling FakeApi#testInlineAdditionalProperties); e.printStackTrace(); }参数param类型Objectrequest body必填。返回类型null空响应体。HTTP 请求头Content-Type 为application/jsonAccept 未定义。 源码中该请求体直接作为localVarPostBody提交并校验非空。2. testJsonFormData使用GET方法访问/fake/jsonFormData测试表单数据的 JSON 序列化两个字符串参数paramfield1与param2field2均为必填实际以表单字段提交源码中放入localVarFormParams但声明的 Content-Type 为application/json。FakeApi apiInstance new FakeApi(); String param param_example; // String | field1 String param2 param2_example; // String | field2 try { apiInstance.testJsonFormData(param, param2); } catch (ApiException e) { System.err.println(Exception when calling FakeApi#testJsonFormData); e.printStackTrace(); }参数NameTypeDescriptionNotesparamStringfield1必填param2Stringfield2必填返回类型null空响应体。HTTP 请求头Content-Type 为application/jsonAccept 未定义。九、从文档到源码FakeApi 生成代码的内部结构文档中每个端点的Example / Parameters / Return type / Authorization / HTTP request headers五段式结构对应源码中固定的代码骨架。以fakeOuterBooleanSerialize为例FakeApi.java 的调用链为fakeOuterBooleanSerialize(body)同步入口委托给WithHttpInfo并取resp.getData()fakeOuterBooleanSerializeWithHttpInfo(body)调用ValidateBeforeCall用TypeTokenBoolean声明返回类型后交给apiClient.execute(call, localVarReturnType)fakeOuterBooleanSerializeValidateBeforeCall(...)可选参数的校验留空仅透传fakeOuterBooleanSerializeCall(...)真正的请求构建方法——设置路径/fake/outer/boolean、清空的 query/form/header 参数表、空 Accept/Content-Type 数组、空认证名数组最后调用apiClient.buildCall(localVarPath, POST, ...)生成okhttp3.Call。异步版本fakeOuterBooleanSerializeAsync(body, callback)会额外把回调包装为上传/下载进度监听器ProgressRequestBody.ProgressRequestListener与ProgressResponseBody.ProgressListener并将网络拦截器挂到apiClient.getHttpClient().networkInterceptors()上实现进度回传——这是 okhttp 拦截器机制在生成客户端中的典型应用。十、测试用例与运行方式仓库提供了与文档一一对应的测试骨架 FakeApiTest.java。该测试类标注了Ignore10 个Test方法fakeOuterBooleanSerializeTest、fakeOuterCompositeSerializeTest、fakeOuterNumberSerializeTest、fakeOuterStringSerializeTest、testBodyWithQueryParamsTest、testClientModelTest、testEndpointParametersTest、testEnumParametersTest、testInlineAdditionalPropertiesTest、testJsonFormDataTest分别调用对应 API 方法并留出// TODO: test validations断言位便于在接入真实服务后补充校验逻辑。在本地构建并运行该生成客户端cd samples/client/petstore/java/okhttp4-gson-parcelableModel mvn clean install将依赖引入自己的 Maven 项目dependency groupIdio.swagger/groupId artifactIdswagger-petstore-okhttp4-gson/artifactId version1.0.0/version scopecompile/scope /dependencyGradle 用户则添加compile io.swagger:swagger-petstore-okhttp4-gson:1.0.0多线程环境下README 建议为每个线程单独创建ApiClient实例避免共享连接与认证状态造成问题。十一、与其他生成变体的关系本示例是 swagger-codegen 众多 Java 客户端变体之一仓库samples/client/petstore/java/下还有 okhttp-gson、okhttp-gson-parcelableModel、jersey2、resttemplate、retrofit2 等。本变体的两个关键差异点在于okhttp4依赖com.squareup.okhttp3:okhttp:4.10.0见 pom.xml使用 OkHttp 4 的 Kotlin 化 API但仍保持 Java 调用兼容parcelableModel所有模型类如 OuterComposite.java实现android.os.Parcelable面向 Android 环境设计。如果你需要为任意 OpenAPI/Swagger 定义生成同样的 Java 客户端可以在仓库根目录使用 README.md 中描述的 codegen CLI 方式指定--library okhttp4-gson与 parcelable 相关配置产出与本文同构的 API 文档与源码。FakeApi 的完整文档还可在 docs 目录 中与 PetApi.md、UserApi.md 等其他 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 生成 Java okhttp-gson-parcelableModel 客户端的 FakeApi 接口调用指南swagger codegen 生成 Java okhttp gson parcelableModel 客户端的 FakeApi 接口调用指南 本文以 swag开发工具代码生成API设计Swagger Codegen 生成的 Java 客户端 PetApi 实战指南okhttp4-gson-parcelableModel 示例Swagger Codegen 生成的 Java 客户端 PetApi 实战指南okhttp4 gson parcelableModel 示例 本指南以 S开发工具代码生成API设计Swagger Codegen 生成的 Java okhttp4-gson 客户端 FakeApi 实战指南十个 /fake 测试端点全解析Swagger Codegen 生成的 Java okhttp4 gson 客户端 FakeApi 实战指南十个 /fake 测试端点全解析 导读 Fake开发工具代码生成API设计上一篇网站离线下载一键搞定WebSite-Downloader 整站保存完整指南下一篇老游戏连不上局域网IPXWrapper 免费复活 IPX/SPX 联机的最简单方案创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考