在zircote/swagger-php中处理对象属性的readOnly标记

在OpenAPI规范中，readOnly属性是一个非常有用的标记，它可以帮助我们明确哪些属性是只读的，不能通过API请求进行修改。然而，在使用zircote/swagger-php库时，开发者可能会遇到一个特殊的情况：当属性类型为对象时，readOnly标记无法正常工作。

问题现象

当我们在PHP类中使用#[OA\Property(readOnly:true)]注解标记属性时，对于基本类型（如字符串）可以正常工作：

#[OA\Property(readOnly:true)]
public string $label;

这会生成正确的OpenAPI规范输出：

"label": {
    "type": "string",
    "readOnly": true
}

但对于对象类型的属性：

#[OA\Property(readOnly:true)]
public Article $article;

生成的OpenAPI规范中却不会包含readOnly标记：

"article": {
    "$ref": "#/components/schemas/Article"
}

原因分析

这种现象实际上是符合OpenAPI规范的预期行为。根据OpenAPI 3.0规范，$ref引用旁边不允许有其他属性共存。而OpenAPI 3.1虽然放宽了限制，但也只允许在$ref旁边添加title和description属性，不包括readOnly。

解决方案

虽然这是规范的限制，但我们仍然可以通过一些技巧来实现对象属性的readOnly标记。一个有效的方法是使用allOf结构：

#[OA\Property(allOf: [new OA\Schema(ref:"#/components/schemas/Article")], readOnly:true)]
public $article;

这会生成包含readOnly标记的OpenAPI规范：

"article": {
  "readOnly": true,
  "allOf": [
    {
      "$ref": "#/components/schemas/Article"
    }
  ]
}

技术背景

allOf是JSON Schema中的一个关键字，它允许我们将多个模式定义组合在一起。在这个解决方案中，我们创建了一个包含两个部分的复合模式：

1. 通过$ref引用Article对象的定义
2. 添加readOnly属性标记

这种模式虽然解决了问题，但需要注意它可能会影响某些OpenAPI工具的处理方式。在实现前，建议测试所有相关工具链对这种结构的支持情况。

最佳实践

对于需要在对象引用上添加额外属性（如readOnly、description等）的情况，建议：

1. 优先考虑是否可以在被引用的模式定义中添加这些属性
2. 如果确实需要在引用点添加，使用allOf结构
3. 在API文档中明确说明这种特殊处理方式
4. 确保所有相关工具（如代码生成器、验证器等）支持这种结构

通过这种方式，我们可以在遵循OpenAPI规范的同时，实现更灵活的API文档定义需求。