开发工具代码生成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 仓库中由 petstore 测试用例自动生成的模型文档samples/client/petstore/java/okhttp4-gson/docs/ReadOnlyFirst.md完整解析其属性表含义并深入追踪从 OpenAPI 定义、代码生成器内部逻辑DefaultCodegen的readOnlyVars处理、Java 模板pojo.mustache到最终生成代码ReadOnlyFirst.java的完整链路。读完本文你将掌握 swagger-codegen 如何识别并处理readOnly属性、为什么只读字段只生成 getter 而不生成 setter以及如何在自己的 OpenAPI 定义中声明并使用这类模型。一、模型文档速览ReadOnlyFirst 是什么ReadOnlyFirst是 swagger-codegen 仓库中用于测试模型生成能力的示例模型之一由 OpenAPISwagger 2.0定义自动生成位于 Java okhttp4-gson 客户端样例中。其自动生成的模型文档 ReadOnlyFirst.md 给出如下属性表NameTypeDescriptionNotesbarString[optional]bazString[optional]从表格可以看出该模型包含两个字段bar、baz类型均为String两个字段都没有额外描述Description 为空两个字段均非必填因此 Notes 列标记为[optional]。这里有一个容易被忽略的细节当前这份文档的表格中并未出现[readonly]标记但字段bar在源 OpenAPI 定义中实际声明了readOnly: true详见下文第三节。文档与定义的这一差异恰好说明了生成样本与当前仓库模板版本之间的历史差异也提醒我们判断字段是否为只读应以 OpenAPI 定义为最终依据而非仅看自动生成的文档。该文档是 swagger-codegen 模型文档模板 pojo_doc.mustache 的输出结果。模板第 6 行定义了属性表的渲染规则{{#vars}}**{{name}}** | ... | {{description}} | {{^required}} [optional]{{/required}}{{#readOnly}} [readonly]{{/readOnly}}也就是说每一行由字段名、类型基本类型加粗显示复杂类型链接到对应的模型文档、描述、以及「非必填标[optional]、只读标[readonly]」的 Notes 列组成。当前仓库模板已支持输出[readonly]标记说明后续版本生成的文档信息会更完整。二、溯源ReadOnlyFirst 的 OpenAPI 定义ReadOnlyFirst模型的定义位于仓库的测试规格文件中fixtures/immutable/specifications/v2/petstorefake.yaml 第 1313 行起ReadOnlyFirst: type: object properties: bar: type: string readOnly: true baz: type: string这是理解整个模型的关键源头bar属性声明了readOnly: true语义为「该字段由服务端生成/维护客户端不应提交修改」baz属性没有任何修饰是普通可读可写字段。在 OpenAPI/Swagger 规范中readOnly: true表示该属性只能出现在响应Response中不能出现在请求Request中。因此生成客户端模型时bar应当只暴露读取能力getter不暴露写入能力setter——这正是 swagger-codegen 生成逻辑的核心行为也是本文重点验证的内容。同样的模型还出现在其他规格文件中如 fixtures/immutable/specifications/v2/samplesServers.yaml第 1274 行与 v3 的 petstore3fake.yaml第 1596 行对应 OpenAPI 3 的components/schemas写法说明该模型被广泛用于跨版本、跨语言生成器的回归测试。三、生成器源码readOnly 属性如何被识别与分类swagger-codegen 的核心类DefaultCodegen负责将 OpenAPI 定义解析为中间模型CodegenModel。在 DefaultCodegen.java 中可以看到完整的属性分类逻辑// set models hasOnlyReadOnly to false if the property is read-only if (!Boolean.TRUE.equals(cp.isReadOnly)) { m.hasOnlyReadOnly false; } ... // if required, add to the list requiredVars if (Boolean.TRUE.equals(cp.required)) { m.requiredVars.add(cp); } else { // else add to the list optionalVars for optional property m.optionalVars.add(cp); } // if readonly, add to readOnlyVars (list of properties) if (Boolean.TRUE.equals(cp.isReadOnly)) { m.readOnlyVars.add(cp); } else { // else add to readWriteVars (list of properties) m.readWriteVars.add(cp); }这段代码揭示了几条关键事实每个属性都会被解析为CodegenProperty并打上isReadOnly标志只读属性被归入readOnlyVars列表可写属性被归入readWriteVars列表若模型存在任何一个非只读属性hasOnlyReadOnly会被置为false用于模板判断「模型是否只包含只读字段」属性还会按是否必填拆分为requiredVars与optionalVars——ReadOnlyFirst的两个字段都不是必填因此都进入optionalVars这与文档表格中两个字段都标[optional]完全对应。四、Java 模板为什么只读字段没有 setter生成 Java 模型代码的模板是 pojo.mustache。其中对每个属性{{#vars}}的渲染分为三部分且全部用{{^isReadOnly}}控制写入能力的生成1链式builder 风格赋值方法——仅非只读字段生成{{#vars}} {{^isReadOnly}} public {{classname}} {{name}}({{{datatypeWithEnum}}} {{name}}) { this.{{name}} {{name}}; return this; } {{/isReadOnly}}2getter——所有字段都会生成ApiModelProperty({{#required}}required {{required}}, {{/required}}value {{{description}}}) public {{{datatypeWithEnum}}} {{#isBoolean}}is{{/isBoolean}}{{getter}}() { return {{name}}; }3传统 setter——仅非只读字段生成{{^isReadOnly}} public void {{setter}}({{{datatypeWithEnum}}} {{name}}) { this.{{name}} {{name}}; } {{/isReadOnly}}可以看到模板设计非常一致只读字段只保留「读」的通道getter彻底移除「写」的通道链式方法和 setter 均不生成从代码层面强制保证客户端不会误写只读字段。五、生成结果解读ReadOnlyFirst.java模板渲染出的最终代码位于 ReadOnlyFirst.java。对照第三节的定义可以逐一印证1字段声明第 32-36 行两个字段均使用 Gson 的SerializedName注解绑定 JSON 字段名默认值均为nullSerializedName(bar) private String bar null; SerializedName(baz) private String baz null;2barreadOnly 字段只生成 getter第 38-45 行/** * Get bar * return bar **/ ApiModelProperty(value ) public String getBar() { return bar; }注意bar没有setBar(...)也没有链式的bar(String bar)方法——这正是pojo.mustache中{{^isReadOnly}}分支生效的直接证据。3baz普通字段同时生成链式方法、getter 和 setter第 47-63 行public ReadOnlyFirst baz(String baz) { this.baz baz; return this; } public String getBaz() { return baz; } public void setBaz(String baz) { this.baz baz; }4样板方法该类还完整生成了equals、hashCode、toString含toIndentedString辅助方法其中equals基于Objects.equals比较两个字段toString输出形如class ReadOnlyFirst { bar: ..., baz: ... }的可读格式便于调试与日志打印。由此可以推断实际使用场景客户端在反序列化服务端响应时通过 Gson 依据SerializedName将 JSON 中的bar、baz值填入对象包括只读的bar而在构造请求时客户端只能设置baz无法触碰只读的bar从类型系统层面保证了 API 契约的正确性。六、okhttp4-gson 库该模型的运行环境ReadOnlyFirst所在样例属于 Java 生成器的okhttp4-gson客户端库对应仓库中的模板目录 modules/swagger-codegen/src/main/resources/Java/libraries/okhttp4-gson以及样例根目录的 README.md。该库的技术栈为OkHttp 4作为 HTTP 客户端负责发送请求与接收响应Gson负责 JSON 序列化/反序列化模型字段通过SerializedName与 JSON 字段一一映射Swagger Annotations通过ApiModelProperty携带模型元信息。模型类位于io.swagger.client.model包同目录下还有ArrayTest、Capitalization、ClassModel等其他由 petstore 测试规格生成模型共同构成生成器的验证样例集。生成的全部模型文档位于 docs 目录每个模型对应一个 Markdown 文档方便开发者在生成后快速查阅字段结构。七、实战启示如何在你的 OpenAPI 定义中使用 readOnly结合上面的完整链路在自己的项目中复用这一机制只需三步第一步在 OpenAPI 定义中声明只读字段。参照 petstorefake.yaml 的写法MyModel: type: object properties: id: type: integer format: int64 readOnly: true # 服务端生成客户端只读 name: type: string # 普通字段可读可写第二步使用 swagger-codegen 生成客户端代码。对 Java 生成器指定--library okhttp4-gson或仓库支持的 jersey2、resttemplate、retrofit2 等库生成后检查id字段只有getId()而name字段同时有链式方法、getName()与setName()。第三步理解约束并在代码中遵守。生成结果即契约请求序列化时不要尝试写入只读字段编译器也会阻止响应反序列化时只读字段自动填充。若需要校验生成行为可对照本文第五节列出的源码路径检查或直接搜索生成的ReadOnlyFirst.java确认 getter/setter 的分布。八、小结ReadOnlyFirst虽是一个仅含两个字符串字段的简单测试模型但它完整承载了 swagger-codegen 对readOnly属性的整套处理逻辑从 OpenAPI 定义的readOnly: true到DefaultCodegen的属性分类readOnlyVars/readWriteVars、requiredVars/optionalVars再到pojo.mustache模板通过{{^isReadOnly}}精确裁剪 setter 与链式方法最终产出「只读字段只有 getter、可写字段方法齐全」的 Java 模型。理解这条链路有助于你在设计 API 契约时正确标注只读字段也便于解读任何 swagger-codegen 生成客户端中某个字段「为何少了 setter」这类常见疑问。赞分享开发工具代码生成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 生成的 ReadOnlyFirst 模型文档解读readOnly 字段在 Java 客户端jersey2-java8中的落地实践Swagger Codegen 生成的 ReadOnlyFirst 模型文档解读readOnly 字段在 Java 客户端jersey2 java8中的落开发工具代码生成API设计Swagger Codegen 生成的 User 模型解析以 okhttp4-gson-parcelableModel Java 客户端为例Swagger Codegen 生成的 User 模型解析以 okhttp4 gson parcelableModel Java 客户端为例 导读 User.开发工具代码生成API设计Swagger Codegen 生成的 ArrayOfNumberOnly 模型Java okhttp4-gson-parcelableModel 客户端的数组模型解析Swagger Codegen 生成的 ArrayOfNumberOnly 模型Java okhttp4 gson parcelableModel 客户端的数开发工具代码生成API设计上一篇LLCOM完全指南如何从零开始掌握这款革命性串口调试神器下一篇ARM架构上的x86程序兼容解决方案Box86技术原理与实施指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 swagger-codegen 生成的 ReadOnlyFirst 模型：readOnly 字段的生成机制与 Java okhttp4-gson 客户端实践
开发工具代码生成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 仓库中由 petstore 测试用例自动生成的模型文档samples/client/petstore/java/okhttp4-gson/docs/ReadOnlyFirst.md完整解析其属性表含义并深入追踪从 OpenAPI 定义、代码生成器内部逻辑DefaultCodegen的readOnlyVars处理、Java 模板pojo.mustache到最终生成代码ReadOnlyFirst.java的完整链路。读完本文你将掌握 swagger-codegen 如何识别并处理readOnly属性、为什么只读字段只生成 getter 而不生成 setter以及如何在自己的 OpenAPI 定义中声明并使用这类模型。一、模型文档速览ReadOnlyFirst 是什么ReadOnlyFirst是 swagger-codegen 仓库中用于测试模型生成能力的示例模型之一由 OpenAPISwagger 2.0定义自动生成位于 Java okhttp4-gson 客户端样例中。其自动生成的模型文档 ReadOnlyFirst.md 给出如下属性表NameTypeDescriptionNotesbarString[optional]bazString[optional]从表格可以看出该模型包含两个字段bar、baz类型均为String两个字段都没有额外描述Description 为空两个字段均非必填因此 Notes 列标记为[optional]。这里有一个容易被忽略的细节当前这份文档的表格中并未出现[readonly]标记但字段bar在源 OpenAPI 定义中实际声明了readOnly: true详见下文第三节。文档与定义的这一差异恰好说明了生成样本与当前仓库模板版本之间的历史差异也提醒我们判断字段是否为只读应以 OpenAPI 定义为最终依据而非仅看自动生成的文档。该文档是 swagger-codegen 模型文档模板 pojo_doc.mustache 的输出结果。模板第 6 行定义了属性表的渲染规则{{#vars}}**{{name}}** | ... | {{description}} | {{^required}} [optional]{{/required}}{{#readOnly}} [readonly]{{/readOnly}}也就是说每一行由字段名、类型基本类型加粗显示复杂类型链接到对应的模型文档、描述、以及「非必填标[optional]、只读标[readonly]」的 Notes 列组成。当前仓库模板已支持输出[readonly]标记说明后续版本生成的文档信息会更完整。二、溯源ReadOnlyFirst 的 OpenAPI 定义ReadOnlyFirst模型的定义位于仓库的测试规格文件中fixtures/immutable/specifications/v2/petstorefake.yaml 第 1313 行起ReadOnlyFirst: type: object properties: bar: type: string readOnly: true baz: type: string这是理解整个模型的关键源头bar属性声明了readOnly: true语义为「该字段由服务端生成/维护客户端不应提交修改」baz属性没有任何修饰是普通可读可写字段。在 OpenAPI/Swagger 规范中readOnly: true表示该属性只能出现在响应Response中不能出现在请求Request中。因此生成客户端模型时bar应当只暴露读取能力getter不暴露写入能力setter——这正是 swagger-codegen 生成逻辑的核心行为也是本文重点验证的内容。同样的模型还出现在其他规格文件中如 fixtures/immutable/specifications/v2/samplesServers.yaml第 1274 行与 v3 的 petstore3fake.yaml第 1596 行对应 OpenAPI 3 的components/schemas写法说明该模型被广泛用于跨版本、跨语言生成器的回归测试。三、生成器源码readOnly 属性如何被识别与分类swagger-codegen 的核心类DefaultCodegen负责将 OpenAPI 定义解析为中间模型CodegenModel。在 DefaultCodegen.java 中可以看到完整的属性分类逻辑// set models hasOnlyReadOnly to false if the property is read-only if (!Boolean.TRUE.equals(cp.isReadOnly)) { m.hasOnlyReadOnly false; } ... // if required, add to the list requiredVars if (Boolean.TRUE.equals(cp.required)) { m.requiredVars.add(cp); } else { // else add to the list optionalVars for optional property m.optionalVars.add(cp); } // if readonly, add to readOnlyVars (list of properties) if (Boolean.TRUE.equals(cp.isReadOnly)) { m.readOnlyVars.add(cp); } else { // else add to readWriteVars (list of properties) m.readWriteVars.add(cp); }这段代码揭示了几条关键事实每个属性都会被解析为CodegenProperty并打上isReadOnly标志只读属性被归入readOnlyVars列表可写属性被归入readWriteVars列表若模型存在任何一个非只读属性hasOnlyReadOnly会被置为false用于模板判断「模型是否只包含只读字段」属性还会按是否必填拆分为requiredVars与optionalVars——ReadOnlyFirst的两个字段都不是必填因此都进入optionalVars这与文档表格中两个字段都标[optional]完全对应。四、Java 模板为什么只读字段没有 setter生成 Java 模型代码的模板是 pojo.mustache。其中对每个属性{{#vars}}的渲染分为三部分且全部用{{^isReadOnly}}控制写入能力的生成1链式builder 风格赋值方法——仅非只读字段生成{{#vars}} {{^isReadOnly}} public {{classname}} {{name}}({{{datatypeWithEnum}}} {{name}}) { this.{{name}} {{name}}; return this; } {{/isReadOnly}}2getter——所有字段都会生成ApiModelProperty({{#required}}required {{required}}, {{/required}}value {{{description}}}) public {{{datatypeWithEnum}}} {{#isBoolean}}is{{/isBoolean}}{{getter}}() { return {{name}}; }3传统 setter——仅非只读字段生成{{^isReadOnly}} public void {{setter}}({{{datatypeWithEnum}}} {{name}}) { this.{{name}} {{name}}; } {{/isReadOnly}}可以看到模板设计非常一致只读字段只保留「读」的通道getter彻底移除「写」的通道链式方法和 setter 均不生成从代码层面强制保证客户端不会误写只读字段。五、生成结果解读ReadOnlyFirst.java模板渲染出的最终代码位于 ReadOnlyFirst.java。对照第三节的定义可以逐一印证1字段声明第 32-36 行两个字段均使用 Gson 的SerializedName注解绑定 JSON 字段名默认值均为nullSerializedName(bar) private String bar null; SerializedName(baz) private String baz null;2barreadOnly 字段只生成 getter第 38-45 行/** * Get bar * return bar **/ ApiModelProperty(value ) public String getBar() { return bar; }注意bar没有setBar(...)也没有链式的bar(String bar)方法——这正是pojo.mustache中{{^isReadOnly}}分支生效的直接证据。3baz普通字段同时生成链式方法、getter 和 setter第 47-63 行public ReadOnlyFirst baz(String baz) { this.baz baz; return this; } public String getBaz() { return baz; } public void setBaz(String baz) { this.baz baz; }4样板方法该类还完整生成了equals、hashCode、toString含toIndentedString辅助方法其中equals基于Objects.equals比较两个字段toString输出形如class ReadOnlyFirst { bar: ..., baz: ... }的可读格式便于调试与日志打印。由此可以推断实际使用场景客户端在反序列化服务端响应时通过 Gson 依据SerializedName将 JSON 中的bar、baz值填入对象包括只读的bar而在构造请求时客户端只能设置baz无法触碰只读的bar从类型系统层面保证了 API 契约的正确性。六、okhttp4-gson 库该模型的运行环境ReadOnlyFirst所在样例属于 Java 生成器的okhttp4-gson客户端库对应仓库中的模板目录 modules/swagger-codegen/src/main/resources/Java/libraries/okhttp4-gson以及样例根目录的 README.md。该库的技术栈为OkHttp 4作为 HTTP 客户端负责发送请求与接收响应Gson负责 JSON 序列化/反序列化模型字段通过SerializedName与 JSON 字段一一映射Swagger Annotations通过ApiModelProperty携带模型元信息。模型类位于io.swagger.client.model包同目录下还有ArrayTest、Capitalization、ClassModel等其他由 petstore 测试规格生成模型共同构成生成器的验证样例集。生成的全部模型文档位于 docs 目录每个模型对应一个 Markdown 文档方便开发者在生成后快速查阅字段结构。七、实战启示如何在你的 OpenAPI 定义中使用 readOnly结合上面的完整链路在自己的项目中复用这一机制只需三步第一步在 OpenAPI 定义中声明只读字段。参照 petstorefake.yaml 的写法MyModel: type: object properties: id: type: integer format: int64 readOnly: true # 服务端生成客户端只读 name: type: string # 普通字段可读可写第二步使用 swagger-codegen 生成客户端代码。对 Java 生成器指定--library okhttp4-gson或仓库支持的 jersey2、resttemplate、retrofit2 等库生成后检查id字段只有getId()而name字段同时有链式方法、getName()与setName()。第三步理解约束并在代码中遵守。生成结果即契约请求序列化时不要尝试写入只读字段编译器也会阻止响应反序列化时只读字段自动填充。若需要校验生成行为可对照本文第五节列出的源码路径检查或直接搜索生成的ReadOnlyFirst.java确认 getter/setter 的分布。八、小结ReadOnlyFirst虽是一个仅含两个字符串字段的简单测试模型但它完整承载了 swagger-codegen 对readOnly属性的整套处理逻辑从 OpenAPI 定义的readOnly: true到DefaultCodegen的属性分类readOnlyVars/readWriteVars、requiredVars/optionalVars再到pojo.mustache模板通过{{^isReadOnly}}精确裁剪 setter 与链式方法最终产出「只读字段只有 getter、可写字段方法齐全」的 Java 模型。理解这条链路有助于你在设计 API 契约时正确标注只读字段也便于解读任何 swagger-codegen 生成客户端中某个字段「为何少了 setter」这类常见疑问。赞分享开发工具代码生成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 生成的 ReadOnlyFirst 模型文档解读readOnly 字段在 Java 客户端jersey2-java8中的落地实践Swagger Codegen 生成的 ReadOnlyFirst 模型文档解读readOnly 字段在 Java 客户端jersey2 java8中的落开发工具代码生成API设计Swagger Codegen 生成的 User 模型解析以 okhttp4-gson-parcelableModel Java 客户端为例Swagger Codegen 生成的 User 模型解析以 okhttp4 gson parcelableModel Java 客户端为例 导读 User.开发工具代码生成API设计Swagger Codegen 生成的 ArrayOfNumberOnly 模型Java okhttp4-gson-parcelableModel 客户端的数组模型解析Swagger Codegen 生成的 ArrayOfNumberOnly 模型Java okhttp4 gson parcelableModel 客户端的数开发工具代码生成API设计上一篇LLCOM完全指南如何从零开始掌握这款革命性串口调试神器下一篇ARM架构上的x86程序兼容解决方案Box86技术原理与实施指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考