CODEWITHSUNDEEP
swaggerswagger-uiswagger-2.0
Leon Li
Leon Li

Reputation: 11

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

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

What I'm doing is defining the following models:

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

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:
  type: object
  allOf: 
    - $ref: ResourceBaseModel
    - type: object
      properties:
        detail_normal_properties:
          type: string
        detail_read_only_properties:
          type: string
          readOnly: true


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:

  1. 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.
  2. 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.
  3. 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!

Upvotes: 1

Views: 1462

Answers (1)

MikeRalphson
MikeRalphson

Reputation: 2393

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.

Upvotes: 1

Related Questions