swagger-ui

swagger-ui copied to clipboard

Content & configuration

Swagger/OpenAPI definition:

{
   type: 'object',
   additionalProperties: {
       $ref: '#/components/schemas/item',
   },
}

Rendered schema in swagger UI :

{
   "additionalProp1": {},
   "additionalProp2": {},
   "additionalProp2": {}
}

Problem :

Here, we're totally losing the context of the objects keys. And users of my api don't know at all what is "additionalProp1" means. In my case, each objects keys are email address and this important information is totally lost.

Possible solution :

If we could rename the automatic key prefix, it would be great ! :

Rendered schema in swagger UI

{
   "dynamicEmailAddress1": {},
   "dynamicEmailAddress2": {},
   "dynamicEmailAddress3": {}
}

But I don't know if it's doable to insert a new property somewhere (like additionalPropertiesPrefix: 'dynamicEmailAddress' in the open api schema, so, sorry in advance if it's not the case.

Thanks

Currently, there's no way to control it, but why not just provide your own example that would be more meaningful?

Yeah seems like the only solution :( But it would mean to hardcode the value structure instead of letting it be auto generated from schema, and I think it is worse. Thanks

Hi!

I have the same issue, swagger-ui generates examples in this way

{ "additionalProp1": { "code": 11, "text": "message text sample" }, "additionalProp2": { "code": 11, "text": "message text sample" }, "additionalProp3": { "code": 11, "text": "message text sample" } }

And I would like to specify a value for the key:

{ "randomUUID1": { "code": 11, "text": "message text sample" } }

Thanks!

I think that I have found the code that generate the response examples. If you go to src/core/plugins/samples/fn.js file and navigate to line 481 you can see this fragment:

const toGenerateCount = schema.minProperties !== null && schema.minProperties !== undefined && propertyAddedCounter < schema.minProperties
          ? schema.minProperties - propertyAddedCounter
          : 4

        for (let i = 1; i < toGenerateCount; i++) {
          if(hasExceededMaxProperties()) {
            return res
          }
          if(respectXML) {
            const temp = {}
            temp["additionalProp" + i] = additionalPropSample["notagname"]
            res[displayName].push(temp)
          } else {
            res["additionalProp" + i] = additionalPropSample
          }
          propertyAddedCounter++
        }

It would be nice if I we can specify the hardcoded number 4 and the string additionalProp.

Do we have a solution here?

Any updates on this topic?

Would love to see some improvements here. Auto-generated examples from schema are great for everything but dictionaries, where this issue forces users to create entirely custom examples since the automatically generated additionalProp#s are not at all descriptive.

I ran into this issue too and created #9739 to resolve this using the standard propertyNames from json schema 2020-12.

Now if you want exactly 2 examples with names dynamicEmailAddress1 and dynamicEmailAddress2:

{
   "dynamicEmailAddress1": {},
   "dynamicEmailAddress2": {}
}

You would write:

{
   propertyNames:
      examples:
      - 'dynamicEmailAddress1'
      - 'dynamicEmailAddress2'
   additionalProperties:
      $ref: "#/components/schemas/Object"
}

The referred object itself could be a full-fledged schema for which the samples will be generated as normal. So the examples are just for the property names.

Alternatively, if the property names should adhere to email format you can also:

{
   propertyNames:
      format: email
   additionalProperties:
      $ref: "#/components/schemas/Object"
}

To get:

{
   "[email protected]": {},
   "[email protected]": {},
   "[email protected]": {}
}

Hope it gets accepted and merged.