Swagger: Add description with ref

Question

I want to add a description to an object property that his definition is referenced. Something like that:

      newCreditCard:
        type: object
        properties:
          billingPhone:
            description: Phone number of the card holder
            $ref: "#/definitions/PhoneNumber"

But the editor warns that the description property will be skipped:

Extra JSON Reference properties will be ignored: description

I have found a less elegant workaround that works for the editor, but not for the Swagger UI (not sure that is may due to the recent update to 3.0.2 version of the Swagger UI)

      newCreditCard:
        type: object
        properties:
          billingPhone:
            description: Phone number of the card holder
            allOf:
            - $ref: "#/definitions/PhoneNumber"

How do you do it in your Swaggers specification?

Thanks for the help!

The workaround from the 2nd example should work in the latest versions of Swagger UI. — Helen, Sep 27 '19 at 11:02

score 1 · Accepted Answer · edited Oct 07 '21 at 07:27

1

If you add anything to the same level of $ref it will be ignored .

json $ref definition https://datatracker.ietf.org/doc/html/draft-pbryan-zyp-json-ref-03#section-3

correct way is to provide the description in the referenced object.

edited Oct 07 '21 at 07:27

Community

1
1

answered Aug 06 '17 at 08:43

Arun Killu

13,581
5
34
61

3

There is an issue about this. 2 years old, still unresolved. https://github.com/OAI/OpenAPI-Specification/issues/556 – Gebb Apr 21 '18 at 19:38
29

There are several phone numbers though, e.g. one is "Phone number of the card holder" but another is "Phone number of the bank" etc. So I don't see how it's "correct" to provide the description in the referenced object, i.e. in the definition of the PhoneNumber type. – ChrisW Nov 22 '19 at 21:33
This answer is true, but it doesn't actually answer the question as posed – Rich Feb 27 '23 at 14:44

score 0 · Answer 2 · answered Mar 24 '17 at 19:39

0

You could simply move the description property to the definition of PhoneNumber. Your original post does not show how you have defined PhoneNumber, but this snippet validates without warnings:

definitions:
  phoneNumber:
    type: string
    description: Phone number of the card holder

  newCreditCard:
    type: object
    properties:
      billingPhone:
        $ref: "#/definitions/phoneNumber"

If this answer is not what you are looking for, please restate the question. We need to know what you are trying to accomplish.

answered Mar 24 '17 at 19:39

Dave Delay

1,292
8
12

19

Assuming the purpose of $ref is to re-use a definition, then the single phoneNumber definition should be available for the 'card holder', a 'mobile', a 'home', a 'fax', a 'work' number... you get the point. Those descriptions cannot all be accommodated in the phoneNumber definition, but would have to be applied to the definitions that *reference* the phoneNumber definition. It appears that Swagger (or is it the underlying JSONReference spec?) makes this difficult, or at least non-obvious. – Steve Henty May 11 '17 at 19:46
4

Addendum: This thread indicates it's a constraint of the JSONReference spec - https://groups.google.com/forum/#!topic/swagger-swaggersocket/ewgimdO2cOI. Agree with all assessments that it's a shame, 'cause it really does make re-use impossible in certain circumstances. – Steve Henty May 11 '17 at 19:50
19

The goal of separating the description property from the `phoneNumber` model is to allow have several properties with different description but using the same model. For example the billingPhone "Phone number of the card holder" , but for example for a fax, the description should be "Fax of the main office". For both all model definition is the same except the description. Thanks for the answer and help – Jonathan Huet May 21 '17 at 21:43

score 0 · Answer 3 · answered Nov 11 '21 at 10:58

although it is not according to JSON standards. if you are using Swashbuckle to generate your swagger. i took advantage over the "Extensions" property of schema. and managed to create a swagger JSON, with $ref and extended properties.


var refSchema = new OpenApiSchema
{      
     //Reference = new OpenApiReference { ExternalResource = referenceLink, Type = ReferenceType.Link }, this wont work and omit all your other properties
    Extensions = new Dictionary<string, IOpenApiExtension>
    {
        { "$ref" , new OpenApiString(referenceLink) } // adding ref as extension cause according to JSON standards $ref shouldnt have any other properties
    },
    Description = prop.Value.Description,
    ReadOnly = prop.Value.ReadOnly,
    Required = prop.Value.Required,
    Type = prop.Value.Type,
    Example = prop.Value.Example,
};

score 0 · Answer 4 · answered Oct 10 '22 at 01:37

For anyone using Swashbuckle with ASP.NET, you can use the following code to have the $ref construct put under the allOf (just like the :

// do this wherever you are calling AddSwaggerGen()
ArgBuilder.Services.AddSwaggerGen(opts => {
  opts.UseAllOfToExtendReferenceSchemas(); // add this line.
});

Now if you have a model with two properties of the same type, the individual descriptions for each field will show up in Swagger UI (e.g. below, both FooHeader and BarHeader are properties of type HttpHeader and their descriptions show up):

Swagger: Add description with ref

4 Answers4

Linked