开发工具代码生成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 生成的 okhttp4-gson 风格 Java API 客户端的开发者以 Petstore 示例项目中的PetApi为样本完整讲解宠物店业务涉及的 8 个接口新增、删除、查询、修改、表单更新、文件上传的方法签名、参数约束、鉴权方式、HTTP 报文特征与返回值类型。文中所有代码与说明均以当前仓库 samples/client/petstore/java/okhttp4-gson 下的生成产物为准并深入源码级实现PetApi.java、ApiClient.java剖析请求构建与执行链路读者读完即可在真实项目中直接套用。文档背景与适用范围PetApi.mdsamples/client/petstore/java/okhttp4-gson/docs/PetApi.md是 swagger-codegen 根据 Swagger Petstore 规范自动生成的 API 参考文档对应的实现类为io.swagger.client.api.PetApi。它描述了一个完整的宠物店 REST 服务客户端所有 URI 均相对于http://petstore.swagger.io:80/v2该地址来自 OpenAPI 规范中的服务器定义实际部署时可通过ApiClient.setBasePath替换。该示例项目属于 okhttp4-gson 模板产物HTTP 层基于 OkHttp 3序列化层基于 Gson。核心依赖可从 pom.xml 确认com.squareup.okhttp3:okhttpHTTP 客户端com.squareup.okhttp3:logging-interceptor日志拦截器com.google.code.gson:gsonJSON 序列化io.gsonfire:gson-fireGson 扩展用于日期/枚举等类型适配org.threeten:threetenbpJava 7 下的日期时间支持io.swagger:swagger-annotations接口总览8 个方法速查表方法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上传宠物图片环境准备与依赖引入参照 samples/client/petstore/java/okhttp4-gson/README.md构建要求Java 1.7 与 Maven/Gradle本地安装mvn clean install远程仓库发布用mvn clean deployMaven 坐标io.swagger:swagger-petstore-okhttp4-gson:1.0.0scope 为 compileGradlecompile io.swagger:swagger-petstore-okhttp4-gson:1.0.0手动方式mvn clean package后安装target/swagger-petstore-okhttp4-gson-1.0.0.jar与target/lib/*.jar。多线程环境下README 明确建议为每个线程单独创建ApiClient实例以避免潜在问题。鉴权方案OAuth2 与 API KeyPetApi 的接口使用两种鉴权声明在 README.md 与各方法文档中petstore_authOAuth2implicit 流程授权 URL 为http://petstore.swagger.io/api/oauth/dialog作用域包括write:pets修改账户中的宠物与read:pets读取账户中的宠物。除getPetById外其余 7 个接口均使用该鉴权。api_keyAPI Key置于 HTTP 头api_key仅getPetById使用。逐个方法实战解析以下每个方法的代码示例均完整来自 PetApi.md参数表、返回类型、Content-Type 与 Accept 字段均与该文档一致。1. addPet新增宠物POST /pet新增一个宠物对象到仓库请求体body为必填的 Pet 对象。// 导入相关类 // 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.PetApi; ApiClient defaultClient Configuration.getDefaultApiClient(); // 配置 OAuth2 访问令牌petstore_auth OAuth petstore_auth (OAuth) defaultClient.getAuthentication(petstore_auth); petstore_auth.setAccessToken(YOUR ACCESS TOKEN); PetApi apiInstance new PetApi(); Pet body new Pet(); // Pet | 需要加入仓库的宠物对象 try { apiInstance.addPet(body); } catch (ApiException e) { System.err.println(Exception when calling PetApi#addPet); e.printStackTrace(); }参数类型说明备注bodyPet需要加入仓库的宠物对象必填返回类型null空响应体鉴权petstore_authContent-Typeapplication/json, application/xmlAcceptapplication/xml, application/json2. deletePet删除宠物DELETE /pet/{petId}petId为必填的LongapiKey为可选的String以api_key请求头传给服务端。PetApi apiInstance new PetApi(); Long petId 789L; // Long | 待删除的宠物 ID String apiKey apiKey_example; // String | 可选 try { apiInstance.deletePet(petId, apiKey); } catch (ApiException e) { System.err.println(Exception when calling PetApi#deletePet); e.printStackTrace(); }参数类型说明备注petIdLong待删除的宠物 ID必填apiKeyString—可选返回类型null空响应体鉴权petstore_authContent-Type未定义Not definedAcceptapplication/xml, application/json3. findPetsByStatus按状态查询GET /pet/findByStatus支持以逗号分隔的多个状态值。status为必填的ListString枚举取值固定为available、pending、sold。返回ListPet。PetApi apiInstance new PetApi(); ListString status Arrays.asList(status_example); // ListString | 需要纳入过滤的状态值 try { ListPet result apiInstance.findPetsByStatus(status); System.out.println(result); } catch (ApiException e) { System.err.println(Exception when calling PetApi#findPetsByStatus); e.printStackTrace(); }参数类型说明备注statusListString需要纳入过滤的状态值必填枚举available、pending、sold返回类型ListPet鉴权petstore_authContent-Type未定义Acceptapplication/xml, application/json4. findPetsByTags按标签查询GET /pet/findByTags支持逗号分隔的多个标签测试时可用tag1, tag2, tag3。tags为必填的ListString返回ListPet。注意从源码看该方法带有Deprecated注解PetApi.java迁移新代码时建议优先使用按状态查询。PetApi apiInstance new PetApi(); ListString tags Arrays.asList(tags_example); // ListString | 用于过滤的标签 try { ListPet result apiInstance.findPetsByTags(tags); System.out.println(result); } catch (ApiException e) { System.err.println(Exception when calling PetApi#findPetsByTags); e.printStackTrace(); }参数类型说明备注tagsListString用于过滤的标签必填返回类型ListPet鉴权petstore_authContent-Type未定义Acceptapplication/xml, application/json5. getPetById按 ID 查询GET /pet/{petId}返回单个Pet对象。该方法是 PetApi 中唯一使用api_key请求头 API Key鉴权的接口。// 配置 API Key 鉴权api_key ApiKeyAuth api_key (ApiKeyAuth) defaultClient.getAuthentication(api_key); api_key.setApiKey(YOUR API KEY); // 如需为 API Key 设置前缀如 Token默认 null取消下一行注释 // api_key.setApiKeyPrefix(Token); PetApi apiInstance new PetApi(); Long petId 789L; // Long | 要返回的宠物 ID try { Pet result apiInstance.getPetById(petId); System.out.println(result); } catch (ApiException e) { System.err.println(Exception when calling PetApi#getPetById); e.printStackTrace(); }参数类型说明备注petIdLong要返回的宠物 ID必填返回类型Pet鉴权api_keyContent-Type未定义Acceptapplication/xml, application/json6. updatePet更新宠物PUT /pet整体替换式更新body为必填的Pet对象报文结构与 addPet 一致。PetApi apiInstance new PetApi(); Pet body new Pet(); // Pet | 需要加入仓库的宠物对象 try { apiInstance.updatePet(body); } catch (ApiException e) { System.err.println(Exception when calling PetApi#updatePet); e.printStackTrace(); }参数类型说明备注bodyPet需要加入仓库的宠物对象必填返回类型null空响应体鉴权petstore_authContent-Typeapplication/json, application/xmlAcceptapplication/xml, application/json7. updatePetWithForm表单更新POST /pet/{petId}以application/x-www-form-urlencoded表单提交name与status两个可选字段路径参数petId必填。PetApi apiInstance new PetApi(); Long petId 789L; // Long | 需要更新的宠物 ID String name name_example; // String | 宠物更新后的名字 String status status_example; // String | 宠物更新后的状态 try { apiInstance.updatePetWithForm(petId, name, status); } catch (ApiException e) { System.err.println(Exception when calling PetApi#updatePetWithForm); e.printStackTrace(); }参数类型说明备注petIdLong需要更新的宠物 ID必填nameString宠物更新后的名字可选statusString宠物更新后的状态可选返回类型null空响应体鉴权petstore_authContent-Typeapplication/x-www-form-urlencodedAcceptapplication/xml, application/json8. uploadFile上传图片POST /pet/{petId}/uploadImage以multipart/form-data上传文件additionalMetadata与file均为可选返回 ModelApiResponse 携带服务端处理结果。PetApi apiInstance new PetApi(); Long petId 789L; // Long | 待更新的宠物 ID String additionalMetadata additionalMetadata_example; // String | 传递给服务端的附加数据 File file new File(/path/to/file.txt); // File | 待上传的文件 try { ModelApiResponse result apiInstance.uploadFile(petId, additionalMetadata, file); System.out.println(result); } catch (ApiException e) { System.err.println(Exception when calling PetApi#uploadFile); e.printStackTrace(); }参数类型说明备注petIdLong待更新的宠物 ID必填additionalMetadataString传递给服务端的附加数据可选fileFile待上传的文件可选返回类型ModelApiResponse鉴权petstore_authContent-Typemultipart/form-dataAcceptapplication/json源码级剖析PetApi 的请求构建与执行链路类结构与 ApiClient 注入PetApi.java 持有私有ApiClient apiClient字段无参构造默认取Configuration.getDefaultApiClient()也支持传入自定义ApiClient并通过getApiClient/setApiClient访问便于替换 basePath、超时、拦截器等。每个方法的三层方法族每个接口在源码中生成三层调用链以addPet为例见 PetApi.javaaddPetCall(...)构建okhttp3.Call负责路径、查询参数、请求头、表单参数与鉴权名的组装addPetValidateBeforeCall(...)先校验必填参数如body null时抛出ApiException(Missing the required parameter ...)再委托给Call构建addPet/addPetWithHttpInfo/addPetAsync同步执行返回业务对象、同步执行返回ApiResponseT可获取状态码与响应头、异步执行基于ApiCallback回调同时返回Call以便取消。WithHttpInfo变体在需要 HTTP 状态码、响应头或原始响应体时使用Async变体内部会把回调包装为ProgressRequestBody.ProgressRequestListener与ProgressResponseBody.ProgressListener从而支持上传/下载进度上报。路径参数与查询参数的生成细节路径参数通过localVarPath.replaceAll(\\{ petId \\}, apiClient.escapeString(petId.toString()))替换如 deletePetCallescapeString定义在 ApiClient.java。集合查询参数findPetsByStatus与findPetsByTags调用apiClient.parameterToPairs(csv, status, status)PetApi.java即逗号分隔拼接多个值parameterToPairs还支持ssv空格、tsv制表符、pipes竖线等格式见 ApiClient.java。请求头localVarHeaderParams.put(api_key, ...)处理可选头参数PetApi.javaselectHeaderAccept/selectHeaderContentType从文档声明的媒体类型数组中选择合适值ApiClient.java。表单参数updatePetWithForm与uploadFile将可选字段放入localVarFormParamsPetApi.javaOkHttp 会自动编码为application/x-www-form-urlencoded或multipart/form-data。鉴权名每次调用通过String[] localVarAuthNames new String[] { petstore_auth }或api_key传给apiClient.buildCall(...)由ApiClient在请求前统一附加对应凭据。响应反序列化与执行带返回值的接口使用TypeTokenListPet(){}.getType()等泛型令牌经apiClient.execute(call, localVarReturnType)ApiClient.java交给 Gson 反序列化无返回值的接口走apiClient.execute(call)ApiClient.java。业务调用失败如 4xx/5xx、反序列化失败统一抛出ApiException其中包含响应码、响应头与错误体信息。测试验证PetApiTest 覆盖全部 8 个接口仓库内已生成对应的单元测试 PetApiTest.java为每个接口提供Test方法addPetTest、deletePetTest、findPetsByStatusTest、findPetsByTagsTest、getPetByIdTest、updatePetTest、updatePetWithFormTest、uploadFileTest见第 45~161 行可作为接口调用签名与参数构造的现成参考模板也是理解生成代码使用方式的直接入口。最佳实践小结每个线程独立持有ApiClient避免共享连接状态只读查询优先使用getPetById/findPetsByStatusfindPetsByTags已标记Deprecated需要状态码或响应头时改用xxxWithHttpInfo需要异步或进度回调时改用xxxAsync所有业务异常统一捕获ApiException必要时基于getCode()分流处理若需要替换 Petstore 测试地址通过ApiClient#setBasePath指向真实服务即可其余调用代码无需改动。相关参考文件PetApi.md、README.md、PetApi.java、ApiClient.java、PetApiTest.java、pom.xml。赞分享开发工具代码生成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 客户端 PetApi 实战指南okhttp4-gson-parcelableModel 示例Swagger Codegen 生成的 Java 客户端 PetApi 实战指南okhttp4 gson parcelableModel 示例 本指南以 S开发工具代码生成API设计swagger-codegen 生成的 Java OkHttp-Gson-Parcelable 客户端 PetApi 完整使用指南swagger codegen 生成的 Java OkHttp Gson Parcelable 客户端 PetApi 完整使用指南 本指南基于 swagger开发工具代码生成API设计swagger-codegen 生成 Dart 浏览器客户端 PetApi 完整指南Petstore 宠物接口调用实战swagger codegen 生成 Dart 浏览器客户端 PetApi 完整指南Petstore 宠物接口调用实战 本指南以 swagger codege开发工具代码生成API设计上一篇WanVideo模型资源宝库一站式获取AI视频生成的核心资产下一篇TensorRT引擎DLL加载难题从快速修复到深度优化创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
