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

Question

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

• Is the overriding feature i am looking at available/supported?

• If so what is the appropriate way of doing it?

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

Answer 1

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