20

I am trying to add a read-only field for 'House' in this example. The house is another model that I want to be read-only.

In this example, the array of Dogs can be set to readOnly without an error, but when I set the single definition of House to readOnly I get the following warning in the Swagger Editor:

Sibling values are not allowed alongside $refs

I understand that this is because everything in the model is inherited here. So how do I define that the write API calls cannot define a 'House' in this endpoint whilst also allowing House to be created and updated in another API endpoints?

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'
Helen
  • 87,344
  • 17
  • 243
  • 314
Mark Hayward
  • 424
  • 1
  • 5
  • 9
  • Related (almost a duplicate): [Overloading description in Swagger file (YAML)](https://stackoverflow.com/q/47155842/113116) – Helen Jul 18 '18 at 12:47

2 Answers2

51

OpenAPI 3.1

In OAS 3.1, schema definitions support sibling keywords alongside $ref:

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

OpenAPI 3.0 and 2.0

Sibling keywords alongside $ref are ignored. The workaround is to use allOf to combine a $ref with other attributes:

  House:
    readOnly: true
    allOf:
      - $ref: '#/definitions/House'
Helen
  • 87,344
  • 17
  • 243
  • 314
  • Using this approach does not work cause `readonly` property won't appear in the output. – Majid Akbari Aug 05 '20 at 10:27
  • 3
    @MajidAkbari it's a tooling issue then. Open an issue with that tool. – Helen Aug 05 '20 at 11:26
  • It works on Swagger UI, but when you try to generate Client SDK (i.e. Java) the output Class are not correctly generated on `openapi: 3.0.x`. Hope with Codegone on `openapi: 3.1.x`. – vlauciani Oct 18 '21 at 08:44
1

I just have found the result and want to share with you like below, you can use readyonly attribute to hide any field:

  • Java code:

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

public String getUserStatus() { return userStatus; }

Shi ka
  • 21
  • 2