开发工具代码生成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 在生成 JavaJersey1客户端时如何处理 OpenAPI / Swagger 定义中的嵌套数组二维数组模型。以自动生成的模型文档 ArrayOfArrayOfNumberOnly.md 为起点沿着文档属性表 → 源 YAML 定义 → 生成后的 POJO 源码的完整链路剖析arrayArrayNumber: ListListBigDecimal这一类型如何从规范描述一步步落地为可调用的 Java 代码。读完本文你将掌握阅读任意 swagger-codegen 生成模型文档的方法并理解嵌套集合类型在生成产物中的形态与用法。一、这份模型文档是什么在 swagger-codegen 生成的客户端工程中每个模型Model都会对应一份独立的 Markdown 文档位于生成的docs/目录下。本文讨论的 ArrayOfArrayOfNumberOnly.md 是 Jersey1 客户端示例工程中为ArrayOfArrayOfNumberOnly模型自动生成的技术参考页全文是一张标准的属性表属性名类型描述备注arrayArrayNumberListListBigDecimal—可选optional这张表虽然只有一行但承载了三条关键信息模型名ArrayOfArrayOfNumberOnly——即仅包含一个数组的数组的模型专门用于测试生成器对深层嵌套集合类型的处理属性名与 Java 类型映射arrayArrayNumber被生成为ListListBigDecimal外层列表的每个元素又是一个ListBigDecimal可选性该属性标注为[optional]意味着在 JSON 中它可以缺失对应到源码中初始值为null。类似地同一目录下的 ArrayOfNumberOnly.md 展示了一维版本arrayNumber: ListBigDecimal二者对照即可清晰看出 swagger-codegen 对一层数组与两层嵌套数组的类型推导差异。二、源定义OpenAPI 中的嵌套数组声明生成的文档并非凭空而来它忠实反映了输入规范中的模型定义。在仓库的测试规范fixtures中可以找到该模型的原始声明。Swagger 2.0v2版本在 petstorefake.yaml 中定义如下ArrayOfArrayOfNumberOnly: type: object properties: ArrayArrayNumber: type: array items: type: array items: type: number关键点在于items的递归嵌套ArrayArrayNumber本身是数组其items又是数组最内层才是type: number。这正是二维数组在 OpenAPI 2.0 中的标准表达方式。OpenAPI 3.0v3版本同一模型也出现在 v3 测试规范 petstore3fake.yaml 中结构完全一致ArrayOfArrayOfNumberOnly: type: object properties: ArrayArrayNumber: type: array items: type: array items: type: number两个版本的规范v2 petstorefake.yaml 与 v3 petstore3fake.yaml都被用于生成样本验证 swagger-codegen 对 2.0/3.0 两种规范格式的嵌套数组解析一致性。另外samplesServers.yaml 与 petstoreMixed3.yaml 也引用了该模型用于其他生成场景。从代码生成器的角度看items层数决定了最终泛型的嵌套深度每多一层items生成的集合泛型就多包一层List。三、生成结果Jersey1 客户端中的 POJO 实现在 Jersey1 示例工程中该模型被生成到 ArrayOfArrayOfNumberOnly.java位于包io.swagger.client.model下。生成后的类是一个典型的 Java BeanPOJO其字段声明精确对应文档中的类型JsonProperty(ArrayArrayNumber) private ListListBigDecimal arrayArrayNumber null;注意这里有两个值得留意的细节JSON 字段名保留了大写源 YAML 中属性名是ArrayArrayNumber首字母大写生成器将其保留为JsonProperty(ArrayArrayNumber)而 Java 字段名则被规范化为驼峰小写arrayArrayNumber。这意味着序列化/反序列化时 JSON 键严格使用ArrayArrayNumber与文档表中展示的属性名小写形式存在大小写差异——阅读生成文档时应以JsonProperty注解为准。数值类型映射为 BigDecimal最内层type: number被映射为java.math.BigDecimal这是 swagger-codegen 在 Java 客户端中处理浮点/高精度数值的默认策略可避免double的精度丢失。生成的方法集除了字段与 getter/setter生成器还为集合属性补充了两个便捷方法public ArrayOfArrayOfNumberOnly arrayArrayNumber(ListListBigDecimal arrayArrayNumber) { this.arrayArrayNumber arrayArrayNumber; return this; } public ArrayOfArrayOfNumberOnly addArrayArrayNumberItem(ListBigDecimal arrayArrayNumberItem) { if (this.arrayArrayNumber null) { this.arrayArrayNumber new ArrayListListBigDecimal(); } this.arrayArrayNumber.add(arrayArrayNumberItem); return this; }arrayArrayNumber(...)流式设置器返回this支持链式调用是生成器为简化构建代码而添加的惯例方法addArrayArrayNumberItem(...)单项追加器在字段为null时先惰性初始化ArrayList再追加避免调用方手动判空。这也是为什么文档中该属性标注[optional]时源码初始值保持null、由追加方法兜底的原因。此外类中还自动生成了基于Objects.equals/Objects.hash的equals()、hashCode()以及格式化输出的toString()通过私有toIndentedString实现 4 空格缩进保证模型可以直接用于断言比较和日志打印。四、一维与二维与 ArrayOfNumberOnly 的对比将 ArrayOfNumberOnly.md 与本模型并列可以直观看出集合层数对生成类型的影响模型源定义 items 层数生成类型ArrayOfNumberOnly1 层array → numberListBigDecimalArrayOfArrayOfNumberOnly2 层array → array → numberListListBigDecimal从源码结构看swagger-codegen 的代码生成模板会依据规范中items的递归深度逐层展开泛型只要规范里继续嵌套items生成类型就会相应扩展为ListListList...。这两个模型被同时收录在 petstore fake 规范中本身就是为覆盖此类嵌套集合类型推导场景而设计的测试用例。五、实际使用构建与读写嵌套数组基于生成后的 POJO调用方可以这样构造一个ArrayOfArrayOfNumberOnly对象ArrayOfArrayOfNumberOnly model new ArrayOfArrayOfNumberOnly() .addArrayArrayNumberItem(Arrays.asList(new BigDecimal(1.1), new BigDecimal(2.2))) .addArrayArrayNumberItem(Arrays.asList(new BigDecimal(3.3)));配合 Jersey1 客户端生成的 JSON 处理代码该工程默认使用 Jackson JsonProperty注解上述对象序列化后的 JSON 大致为{ ArrayArrayNumber: [ [1.1, 2.2], [3.3] ] }读取时同样按两层列表遍历即可for (ListBigDecimal row : model.getArrayArrayNumber()) { for (BigDecimal value : row) { // 处理每个数值 } }由于字段默认值为null对应[optional]读取前建议先判空或依赖addArrayArrayNumberItem的惰性初始化来规避空指针。六、如何在自己的项目中复现与验证如果你想在本地复现这份文档与代码的生成过程仓库提供了完整的样本与规范输入规范使用 petstorefake.yamlSwagger 2.0或 petstore3fake.yamlOpenAPI 3.0其中都包含ArrayOfArrayOfNumberOnly模型生成目标选择 Java 客户端的jersey1生成器生成命令通过仓库根目录的 pom.xml 构建出 CLI 后使用java -jar modules/swagger-codegen-cli/target/swagger-codegen-cli.jar generate -i 规范路径 -l java -c 配置配置示例可参考 java-client.xml执行生成校验产物生成后检查输出工程中的src/main/java/io/swagger/client/model/ArrayOfArrayOfNumberOnly.java与docs/ArrayOfArrayOfNumberOnly.md应与仓库 samples/client/petstore/java/jersey1 目录下的现有产物一致。小结通过ArrayOfArrayOfNumberOnly这一个模型我们可以完整观察到 swagger-codegen 处理嵌套数组的三层映射关系OpenAPI 规范中的递归items声明 → 生成文档属性表中的ListListBigDecimal→ Java POJO 中的泛型字段与便捷方法。这份模型文档虽然只有一张属性表却是理解生成器类型推导、JSON 字段命名规则与集合便捷方法设计的绝佳切片。后续阅读其他生成模型文档如 Pet.md、Order.md时都可以沿用本文的文档表 → 源定义 → 生成源码三步分析法。赞分享开发工具代码生成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 生成 C 模型解析从 OpenAPI 二维数组定义到 ListListdecimal?以 ArrayOfArrayOfNumberOnly 为例swagger codegen 生成 C 模型解析从 OpenAPI 二维数组定义到 ListListdecimal? 以 ArrayOfArrayOf开发工具代码生成API设计swagger-codegen 生成 C 模型文档解析以 ArrayOfArrayOfNumberOnly 嵌套数组模型为例swagger codegen 生成 C 模型文档解析以 ArrayOfArrayOfNumberOnly 嵌套数组模型为例 本篇技术指南围绕 swagger开发工具代码生成API设计swagger-codegen 嵌套数组模型解析以 google-api-client 生成的 ArrayOfArrayOfNumberOnly 为例swagger codegen 嵌套数组模型解析以 google api client 生成的 ArrayOfArrayOfNumberOnly 为例 本指南开发工具代码生成API设计创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考