Using different Swagger Models properties for collection/detail request/response

Question

I'm beginner of Swagger, and I'm trying to define endpoints which have:

Some read-only properties that isn't allowed in request but show in response
Some white-only properties and hidden that allowed in request but not show in response
Some properties only on collection level at /resources, but some other additional details on /resources/resource-id

What I'm doing is defining the following models:

ResourceBaseModel: this saves all the shared properties of all

ResourceBaseModel:
  type: object
  properties:
    shared_properties:
      type: string

ResourceCollectionResponse: this is wrapping the response additional properties

ResourceCollectionResponse:
  type: array
  items:
    type: object
    allOf: 
      - $ref: ResourceBaseModel
      - type: object
        properties:
          collection_normal_properties:
            type: string
          collection_read_only_properties:
            type: string
            readOnly: true

ResourceDetailResponse: this is adding different properties for response

ResourceDetailResponse:
  type: object
  allOf: 
    - $ref: ResourceBaseModel
    - type: object
      properties:
        detail_normal_properties:
          type: string
        detail_read_only_properties:
          type: string
          readOnly: true

ResourceRequest: same, add additional and write-only properties

ResourceRequest:
  type: object
  allOf: 
    - $ref: ResourceBaseModel
    - type: object
      properties:
        request_write_only_properties:
          type: string

This is making every model defined 4 times and I feel it's not efficient.

So here are my questions:

I saw there is a discriminator in Swagger Spec. Should I use this with "allOf" of these extended models? From result, using of not using this discriminator, the result looks the same as long as "allOf" used.
the "readOnly", if defined in base level, still shows in Swagger UI and needs special handling or filtering when using or generating docs. The demo data in request is also showing these readOnly properties in Swagger UI request (but only the model added a label of "read-only"). Is there any better solution besides what I'm trying.
the "white-only", as far as I know, is not supported. Is defining a new model the only way?

I wonder if there will be one day I can define only one model to describe all of the models, or do you think an innovative language that can compile to Swagger YAML can benefit the whole community? Like how Sass/LESS builds CSS?

Thanks for your help and insightes!

MikeRalphson MikeRalphson · Accepted Answer · 2017-12-20T19:02:28

OpenAPI 3.0.x supports writeOnly as well as readOnly schema properties. This should allow you to simplify your models, the allOf / discriminator should not be necessary.

Using different Swagger Models properties for collection/detail request/response

1 Answers