企业官网建设流程全解析

• 开发工具
• 代码生成
• API设计

本文以 swagger-codegen 在 Java Jersey1 客户端样例中生成的模型文档 ReadOnlyFirst.md 为主体，讲解 OpenAPI/Swagger 定义中的readOnly属性如何被模板引擎翻译成模型 API 文档、Java POJO 与注释约定。读完本文，你将能看懂任意一个由 swagger-codegen 生成的docs/*.md模型文档的结构，并理解只读属性在客户端代码中的落地形态。

文档来源：一份典型的生成式模型文档

ReadOnlyFirst.md是 swagger-codegen 对 petstore 测试定义（fixtures/immutable/specifications/v2/petstorefake.yaml）中ReadOnlyFirst模型执行代码生成后，自动产出的文档文件，位于 samples/client/petstore/java/jersey1/docs/ 目录。它不属于手写文档，而是由 Java 生成器模板 Java/pojo_doc.mustache 渲染得到。

原文档正文如下：

# ReadOnlyFirst ## Properties Name | Type | Description | Notes ------------ | ------------- | ------------- | ------------- **bar** | **String** | | [optional] **baz** | **String** | | [optional]

虽然篇幅简短，但它承载了完整的信息结构：模型名、属性表头（Name / Type / Description / Notes），以及每个属性在 Notes 列中通过[optional]标注的可选性信息。后续内容将逐层拆解这份文档背后的生成原理与代码落地。

模型文档的生成模板与渲染逻辑

所有 Java 客户端（含 jersey1）的模型文档都由模板 modules/swagger-codegen/src/main/resources/Java/pojo_doc.mustache 渲染。模板核心逻辑如下：

# {{classname}} ## Properties Name | Type | Description | Notes ------------ | ------------- | ------------- | ------------- {{#vars}}**{{name}}** | {{#isEnum}}...{{/isEnum}}{{^isEnum}}{{#isPrimitiveType}}**{{datatype}}**{{/isPrimitiveType}}{{^isPrimitiveType}}**{{datatype}}**{{/isPrimitiveType}}{{/isEnum}} | {{description}} | {{^required}} [optional]{{/required}}{{#readOnly}} [readonly]{{/readOnly}} {{/vars}}

从中可以提炼出三条渲染规则：

1. 名称与类型列：属性名加粗输出；如果属性是基本类型（如String、Integer）直接打印类型名；如果是复杂类型（其他模型、容器），则输出指向对应模型文档的 Markdown 链接（例如[ReadOnlyFirst](https://link.gitcode.com/i/41d411206e5ea18f18137d0866b1e8ad)）。
2. Description 列：直接输出 OpenAPI 定义中description字段的值（ReadOnlyFirst的bar、baz均未填写 description，因此该列为空）。
3. Notes 列：required为假时追加[optional]；readOnly为真时追加[readonly]。ReadOnlyFirst.bar与baz均非必填，因此都只有[optional]。

注意：ReadOnlyFirst.bar在 YAML 定义中标记了readOnly: true，但其 Java 客户端模型文档却未出现[readonly]标注。原因在于该示例对应的 Java 生成器模板（如 Java/pojo_doc.mustache）版本中并未将{{#readOnly}}分支渲染进最终的模型文档表（相比之下，csharp/model_doc.mustache、go/model_doc.mustache 等语言模板则会在 Notes 列输出[readonly]）。因此阅读ReadOnlyFirst.md时，"只读"信息需要结合生成后的 Java 源码（ReadOnlyFirst.java）或原始 YAML 定义确认。

从 OpenAPI 定义到文档：ReadOnlyFirst 的源头

ReadOnlyFirst模型定义位于 fixtures/immutable/specifications/v2/petstorefake.yaml（第 1313–1320 行）：

ReadOnlyFirst: type: object properties: bar: type: string readOnly: true baz: type: string

• bar：type: string且readOnly: true，语义上表示该字段由服务端生成/维护，客户端不应提交。
• baz：普通type: string，未标记只读，也未在required列表中，因此是可选的读写字段。

同一 YAML 中还定义了对照模型hasOnlyReadOnly（第 1321–1329 行），其两个属性bar、foo全部为readOnly: true，用于专门测试"仅含只读字段"的模型生成。该模型生成的 Java 类 HasOnlyReadOnly.java 与ReadOnlyFirst的关键差异是：两个属性都只有 getter，没有任何 setter。

只读属性在生成代码中的落地：getter 与 setter 的取舍

对比两份生成的 Java 源码，可以直观看到readOnly对代码生成的实际影响（这是模型文档 Notes 列所不体现的细节）：

具体到 ReadOnlyFirst.java：

• 字段声明统一使用@JsonProperty("bar")/@JsonProperty("baz")绑定 JSON 属性名；
• bar只有getBar()，没有setBar()，也没有 builder 风格的链式赋值方法——这是readOnly: true的直接产物；
• baz则具备完整的 getter、setter 以及返回this的链式方法baz(String baz)，方便流式构造对象。

因此，"只读字段"在客户端模型中的含义是：反序列化时服务端返回的bar可以被读取，但客户端不能通过 setter 主动设置该字段。这从结构上防止了客户端向只读字段写入与协议不符的数据。

只读属性的组合使用：ArrayTest 与泛型容器

ReadOnlyFirst不仅在独立模型中作为属性出现，也被其他模型复用。例如 ArrayTest.java 中声明了private List<List<ReadOnlyFirst>> arrayArrayOfModel，提供addArrayArrayOfModelItem(...)、getArrayArrayOfModel()、setArrayArrayOfModel(...)等访问方法。此时ReadOnlyFirst以复杂类型身份出现在其他模型的文档 Notes 列链接中（[**ReadOnlyFirst**](https://link.gitcode.com/i/41d411206e5ea18f18137d0866b1e8ad)），形成模型文档之间的交叉引用。这也解释了模板中{{^isPrimitiveType}}分支存在的意义：非基本类型一律输出指向对应.md的链接，保证生成的文档集合互相可达、可以整体作为 API 客户端手册使用。

只读字段的语义边界与阅读提示

从 fixtures/immutable/specifications/v2/petstorefake.yaml 中还可以找到更多readOnly: true的使用点（如Name模型的snake_case、123Number属性），说明该标记在测试规格中覆盖了多种命名与类型场景，用于验证生成器对不同形态只读字段的处理一致性。

在阅读ReadOnlyFirst.md这类生成文档时，建议遵循以下要点：

1. [optional]仅代表"不在required列表中"，与是否只读无关；bar同时具备 optional 与 readOnly 两种语义。
2. Notes 列是否显示[readonly]取决于具体语言的生成模板，Java jersey1 样例未渲染该标注，应以生成源码的 getter/setter 结构为准。
3. 想要确认某个属性的读写能力，最可靠的方式是查看对应 src/main/java/io/swagger/client/model/ 下的 POJO：有 setter 即可写，只有 getter 即只读。
4. 模型文档之间通过类型名链接相互引用，可作为客户端 SDK 的目录索引使用。

相关资源

• 模型文档：samples/client/petstore/java/jersey1/docs/ReadOnlyFirst.md
• 生成源码：ReadOnlyFirst.java、HasOnlyReadOnly.java、ArrayTest.java
• 生成模板：modules/swagger-codegen/src/main/resources/Java/pojo_doc.mustache
• 规格定义：fixtures/immutable/specifications/v2/petstorefake.yaml（ReadOnlyFirst见第 1313–1320 行，hasOnlyReadOnly见第 1321–1329 行）

• 开发工具
• 代码生成
• API设计