1

Is it possible to somehow mark properties so that it's understandable which field should be set in SwaggerUI when sending request.

For example we have a route for payments, which has payment_type property that can hold values like paypal, credit_card, crypto, etc. and based on that field we need to fill different properties like below.

{
  "payment": 0,
  "paypal": "test@test.com",
  "cryptocurrency": "test",
  "wallet_address": "test",
  "swift": "test",
  "iban": "test",
  "account_name": "test",
  "bank_name": "test"
}

Is it possible to mark them somehow so that they are grouped, like for crypto cryptocurrency and wallet_address should be set, while for bank transfer swift, iban, account_name and bank_name should be set.

Helder Sepulveda
  • 15,500
  • 4
  • 29
  • 56
DoubleK
  • 542
  • 3
  • 16
  • Possible duplicate of [Swagger: variant schema shape dependant on field value](https://stackoverflow.com/questions/46557096/swagger-variant-schema-shape-dependant-on-field-value). Related: [Swagger Inheritance and Composition](https://stackoverflow.com/q/27862407/113116), [“discriminator” in polymorphism, OpenAPI 2.0 (Swagger 2.0)](https://stackoverflow.com/a/39730295/113116), [OpenAPI documentation for a single endpoint multiple posts request](https://stackoverflow.com/q/46250030/113116) – Helen Jul 16 '18 at 13:57
  • Can you provide a minimal swagger definition that uses this model? I would like to try incorporating what @Helen mentioned in the the comments... lets see if that makes it understandable which field should be set in SwaggerUI when sending request. – Helder Sepulveda Jul 16 '18 at 14:58

1 Answers1

1

No, there is no such an option. We are limited by the OpenAPI-Specification, read the Parameter Object section to see a list of available fields.

Now knowing that limitation not everything is lost, here are a few options:

  • You do have description that is a good place to add your details.

  • You also can go with a Specification Extension but that will not be something that the swagger-ui will support by default, if you need the UI to take action on your extension(s) you will need to code it.

  • Another option pointed out in the comments by @Helen is using discriminator but that is not currently supported by the swagger-ui:
    https://github.com/swagger-api/swagger-ui/issues/2438

Helder Sepulveda
  • 15,500
  • 4
  • 29
  • 56
  • 1
    `there is no such an option` - actually `discriminator` can be used for this kind of scenario, as [explained here](https://stackoverflow.com/a/46575120/113116). – Helen Jul 16 '18 at 14:03
  • @helen is that possible for flat structure or just objects? – DoubleK Jul 16 '18 at 14:29
  • @DoubleK What do you mean by "flat structure"? – Helen Jul 16 '18 at 14:31
  • @helen by flat I mean ``` { "payment": 0, "paypal": "test@test.com", "cryptocurrency": "test", "wallet_address": "test", "swift": "test", "iban": "test", "account_name": "test", "bank_name": "test" } ``` and as object I mean ``` { "payment": 0, "crypto": { "cryptocurrency": "test", "wallet_address": "test" }, "bank": { "swift": "test", "iban": "test", "account_name": "test", "bank_name": "test" } } ``` – DoubleK Jul 16 '18 at 14:43
  • 1
    @Helen Thanks for the tip about `discriminator` I personally never used that before ... and I'm struggling to create an example that satisfies the question: > How to make it understandable which field should be set in SwaggerUI when sending request? – Helder Sepulveda Jul 16 '18 at 15:04
  • 1
    @DoubleK: `discriminator` works for "flat" objects and _may_ work for nested objects too depending on the use case - e.g. model inheritance/composition lets you vary top-level properties, but probably not nested properties. Check out the [example](https://stackoverflow.com/q/46557096/113116) in the linked question - it's very similar to your case, just the property names are different. – Helen Jul 16 '18 at 15:06
  • 1
    @HelderSepu *"How to make it understandable which field should be set in SwaggerUI when sending request?"* Good question. You can define `discriminator` and model inheritance/composition in the API definition, but Swagger UI currently [does not support](https://github.com/swagger-api/swagger-ui/issues/2438) switching input models based on `discriminator`. [This answer](https://stackoverflow.com/a/39730295/113116) mentions an alternative documentation renderer that supports `discriminator` - if that's an option. – Helen Jul 16 '18 at 15:16
  • @helen that's exactly my problem `but Swagger UI currently does not support switching input models based on discriminator` :( – DoubleK Jul 18 '18 at 11:51