CODEWITHSUNDEEP
openapi
zuda
zuda

Reputation: 141

Is there a way to override properties' description and example in OAS3?

I have been looking for resources about inheritance in OAS3 but the closest i get is https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md and the above did not have answer i am looking for.

This is the working example

components:
  schemas:
    Pet:
      properties:
        no_legs:
          description: "Number of legs"
          type: number
          example: 4
    Duck:
      allOf:
        - $ref: '#/components/schemas/Pet'
        - type: object
          properties:
            no_legs:
              example: 2
      properties:
        no_legs:
          description: 'Number of webbed feet'

Failing example that was inspired by the spec

    Duck:
      allOf:
        - $ref: '#/components/schemas/Pet'
        - type: object
          properties:
            no_legs:
              description: 'Number of webbed feet'
              example: 2

My questions are

I understood that i can use composition to tackle this issue but i will have a lot of the definition being repeated.

Upvotes: 14

Views: 12121

Answers (1)

Aleksi
Aleksi

Reputation: 5036

Yes, that's essentially the way to go about overriding properties. What sort of error are you getting on your failing example? It works just fine at https://editor.swagger.io/ at least. Did you remember to specify openapi: 3.0.0 at the root of your document?

Note that the following two definitions are identical:

Duck:
  allOf:
    - $ref: '#/components/schemas/Pet'
    - type: object
      properties:
        no_legs:
          description: 'Number of webbed feet'
          example: 2

Duck:
  allOf:
    - $ref: '#/components/schemas/Pet'
  properties:
    no_legs:
      description: 'Number of webbed feet'
      example: 2

Upvotes: 8

Related Questions