如何在OpenAPI（Swagger）中将$ref属性声明为只读？

Question

我试图在这个例子中为“House”添加一个只读字段。房屋是另一个我想要设置为只读的模型。

在这个例子中，狗的数组可以设置为readOnly而不会出错，但是当我将House的单个定义设置为readOnly时，Swagger编辑器会显示以下警告：

$refs旁边不允许有兄弟值。

我理解这是因为此处继承了模型中的所有内容。那么，如何定义在此端点中写入API调用不能定义“House”，同时又允许在其他API端点中创建和更新“House”？

Pets:
  properties:
    id:
      type: string
      example: AAAAE12-1123AEF-1122312123
      readOnly: true
    name:
      type: string
      example: My Default Name
    text:
      type: string
      example: My Default Text
  Dogs:
    type: array
    readOnly: true
    items:
      $ref: '#/definitions/Dog'    
  House:
    readOnly: true
    $ref: '#/definitions/House'

- Mark Hayward

---

相关（几乎是重复的）：Swagger文件（YAML）中的重载描述 - Helen

Answer 1

OpenAPI 3.1

OAS 3.1中，模式定义支持$ref关键字的同级关键字：

House:
  $ref: '#/components/schemas/House'
  readOnly: true

OpenAPI 3.0和2.0

与$ref并列的兄弟关键字将被忽略。解决方法是使用allOf将$ref与其他属性组合：

  House:
    readOnly: true
    allOf:
      - $ref: '#/definitions/House'

- Helen

---

使用这种方法不起作用，因为“readonly”属性不会出现在输出中。 - Majid Akbari

@MajidAkbari，那就是工具问题了。在该工具上开一个问题。 - Helen

它在Swagger UI上运行良好，但是当您尝试生成客户端SDK（即Java）时，在openapi: 3.0.x上输出的类未正确生成。 希望在openapi: 3.1.x上与Codegone一起实现。 - vlauciani

Answer 2

我刚刚找到了结果，想与您分享，您可以使用readyonly属性隐藏任何字段：

• Java代码：

@ApiModelProperty(example = "1", readOnly = true, value = "用户状态")

public String getUserStatus() { return userStatus; }

• Swagger: 在此输入图像描述

- Shi ka

---

问题中没有提到Java，这个答案并不有用。 - techvice

@techvice 确实如此，但这对我有帮助，因为我需要通过注释来声明它。 - elonderin

在较新版本的Swagger中，注释已更改为@Schema(accessMode = Schema.AccessMode.READ_ONLY)。 - Karl Henselin