Forum Discussion

HenrikHL's avatar
HenrikHL
Frequent Contributor
12 months 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 email type of this Domain using a $ref from the APIs

Problem:

In one of the APIs I want to change the description. How is this best done?

 

I don't want to define 2 identical simple types with different names (email and email2)!

Reason: If I in the future would like to modify the maxLength to 150 - I only want to modify this one place and not remember to modify it multiple places. I don't mind having 2 simple types defined - but one must somehow inherit the properties from the other simple type and "just" overwrite the description...

8 Replies

Sort By
  • chichepo's avatar
    chichepo
    Champion Level 3
    12 months ago

    HenrikHL 

    If you are using OAS3 an up, you should consider using allOf (here some doc)
    Then you can use a different description when it's relevant

  • HenrikHL's avatar
    HenrikHL
    Frequent Contributor
    12 months 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 3
      12 months 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?

  • HenrikHL's avatar
    HenrikHL
    Frequent Contributor
    12 months ago

    chichepo as mentioned previously I have also vastly used this pattern - here is an example of overwriting the `example` value of `isShipperOwned` property

    Apparently SwaggerHub accepts this pattern. I tried the same in reDocly - but here it does not work. I have not tried it - but this (mis)use of allOf also breaks code-generators. Have you tried to generate code via the SwaggerHub page? Does the code generated work?

    The new OAS 3.1 allows for a "description"-sibling next to the $ref. In OAS 3.1 you can overwrite (legally) the description of a field you are referring to ($ref)

    Unfortunately you still cannot overwrite the `example` property 😞

    • chichepo's avatar
      chichepo
      Champion Level 3
      12 months ago

      HenrikHL 

      Apparently SwaggerHub accepts this pattern. I tried the same in reDocly - but here it does not work.

      I was not aware about such issue on redocly. You are rigth it is, obviously, not supported.

      SwaggerHubRedocly

       


      Regarding the code generation, in my previous response, the code was generated correctly, but "description" or "example" are not "demonstrative" attributes when talking about codegen.
      I'll try something like dealing with different patterns or types.
      I'll let you know. 

       

      • chichepo's avatar
        chichepo
        Champion Level 3
        12 months ago

        HenrikHL 
        I dug a little deeper in using allOf and the code generation.
        Look at the 2 cases I tried.

        Case #1:

        Yaml definitionSwaggerHub DocC# code generated

         

         

         

        Case #2:

        Yaml DefinitionSwaggerHub DocC# code generated

         

        I am not sure if it is what you meant when you asked:
        "Have you tried to generate code via the SwaggerHub page?"

        I was expecting to get class model that support the whole properties list.

        I am looking to hear, in this forum, some comments about this code.