CODEWITHSUNDEEP
swaggerswagger-2.0
Karsten S.
Karsten S.

Reputation: 2391

How to specify alternating parameters in swagger?

Is it possible (and how) to specify additional parameters that depend on the value of another given parameter?

Example

I have a call PUT /accounts/<account_id>/payment_method which takes some parameters besides the path parameter.

One is payment_method_type which defines the payment method to be set.

Now: if payment_method_type is DD for direct debit, there are some more parameters allowed (and needed) like account_holder and iban. If it is something else, e. g. PP, other parameters are needed.

Excerpt from the json

"parameters": {
  "payment_method_type": {
    "name": "type",
    "description": "Payment method type.",
    "in": "query",
    "required": true,
    "type": "string",
    "enum": [
      "DD", "IV", "PP"
    ]
  },
  "payment_method_data_dd_account_holder": {
    "name": "account_holder",
    "description": "Name of account holder",
    "in": "query",
    "required": false, # but true if payment_method_type == DD
    "type": "string"
  },
  "payment_method_data_dd_iban": {
    "name": "iban",
    "description": "IBAN",
    "in": "query",
    "required": false, # but true if payment_method_type == DD
    "type": "string"
  },
  "payment_method_data_pp_some_info": {
    "name": "some_info",
    "description": "Some info needed for PP",
    "in": "query",
    "required": false, # but true if payment_method_type == PP
    "type": "string"
  },
}
"paths": {
  "/accounts/{account_id}/payment_method": {
    "put": {
      "summary": "Update Payment Method",
      "description": "...",
      "parameters": {
        {
          "$ref": "#/parameters/path_psp_account_id"
        },
        {
          "$ref": "#/parameters/payment_method_type"
        },
        {
          "$ref": "#/parameters/payment_method_data_dd_account_holder"
        },
        {
          "$ref": "#/parameters/payment_method_data_dd_iban"
        },
        {
          "$ref": "#/parameters/payment_method_data_pp_some_info"
        },
      }
    }
  }
}

I'd like to get rid of the long parameter list (since there are more parameters left out here) but group them as described above and document that some parameters are required (and allowed) only for special types.

Is there a way to describe this?

Is there a way to define sets of parameters like all the direct debit parameters in one definition and reference it? Remark: those parameters are given next to the payment_method_type parameter and not inside a sub-object.

Upvotes: 3

Views: 1186

Answers (1)

fehguy
fehguy

Reputation: 6824

There is no way to have conditional parameters in the current swagger specification.

Yes, the parameters array allows a $ref pointer.

Upvotes: 1

Related Questions