如何在 OpenAPI (Swagger) 中将 $ref 属性声明为只读？答案

【问题标题】：How to declare a $ref property as readOnly in OpenAPI (Swagger)?如何在 OpenAPI (Swagger) 中将 $ref 属性声明为只读？
【发布时间】：2018-12-26 09:10:03
【问题描述】：

我正在尝试在此示例中为“House”添加一个只读字段。房子是另一个我想只读的模型。

在此示例中，Dogs 数组可以设置为 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'

【问题讨论】：

相关（几乎重复）：Overloading description in Swagger file (YAML)

标签： swagger swagger-2.0 openapi

【解决方案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'

【讨论】：

使用此方法不起作用，因为readonly 属性不会出现在输出中。
@MajidAkbari 那么这是一个工具问题。使用该工具打开一个问题。
它适用于 Swagger UI，但是当您尝试生成客户端 SDK（即 Java）时，openapi: 3.0.x 上未正确生成输出类。希望在 openapi: 3.1.x 上使用 Codegone。

【解决方案2】：

我刚找到结果，想和你分享如下，你可以使用readyonly属性隐藏任何字段：

Java 代码：

@ApiModelProperty(example = "1", readOnly = true, value = "User status")

public String getUserStatus() { return userStatus; }

招摇： enter image description here

【讨论】：

他们没有在问题的什么地方询问有关 Java 的问题。这个答案没有帮助。