Forum Discussion

HenrikHL's avatar
HenrikHL
Frequent Contributor
2 years ago

Overwriting descriptions on reusable objects

I have a simple type defined in a Domain used in multiple APIs:     email: type: string maxLength: 100 description: `E-mail` address to be used example: 'info@dcsa.org'     I refer to...
HenrikHL's avatar
HenrikHL
Frequent Contributor
2 years ago

Hi chichepo,

 

Thank you for your proposal 🙂

To be honest - this is what I have been doing for the last year - but I have been notified that this is a misuse of allOf - it is not valid construct in OpenAPI.

Please check this link: https://github.com/OAI/OpenAPI-Specification/issues/2026#issuecomment-1034728350

The link that you refer to above also does not give an example of extending attributes of a property (example or description) - the docs only focus on merging attributes of multiple objects

On the same GitHub issue I link to above - it seems that next version of OAS (3.1) will support $ref with a sibling description property: https://github.com/OAI/OpenAPI-Specification/issues/2026#issuecomment-618651680

 

  • chichepo's avatar
    chichepo
    Champion Level 1
    2 years ago

    HenrikHL 
    I am curious about this post because I am already using such kind of construction with OAS 3.0.3
    Look at this example:

     

     Without sibling descriptionWith sibling description
    Object/properties definition
    Documentation

     

    Generated C# Server Code

     

     


    The OAS 3.1 seems to talk about a "Real" sibling capability for such attribute (meaning without need to use allOf).

    What I am missing here?