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.
There is no way to have conditional parameters in the current swagger specification.
Yes, the parameters array allows a $ref pointer.
Related
I'm not very strong in swagger 2.0, could you please help me? I'm trying to describe body parameters, but got an error. Here is my swagger.json file:
{
"swagger": "2.0",
"info": {
"title": "Simple API overview",
"version": "v2"
},
"host": "localhost:4000",
"basePath": "/",
"paths": {
"/user/register": {
"post": {
"operationId": "register",
"summary": "User registration",
"parameters": [{
"in": "body",
"name": "role",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
}]
}
}
}
}
When I try to run it, I got an error:
Error: Expected `string` for value, got `1`
If I remove example field, I got this in Example Value section:
{}
Looks like the type definition is incorrect, but I couldn't figure out what's the difference between my code and examples from swagger docs.
Any help is appreciated.
Thanks.
I found the reason: there should be consumes field defined as text/plain. By default it is application/json.
The full code:
{
"swagger": "2.0",
"info": {
"title": "Simple API overview",
"version": "v2"
},
"host": "localhost:4000",
"basePath": "/",
"paths": {
"/user/register": {
"post": {
"operationId": "register",
"summary": "User registration",
"consumes": ["text/plain"],
"parameters": [{
"in": "body",
"name": "role",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
}]
}
}
}
}
One way to get around this error is to change type from integer to string.
"parameters": [{
"in": "body",
"name": "role",
"required": true,
"schema": {
"type": "string",
"example": "1"
}
}]
I get the following error when creating API in Postman: "Invalid data type. Must be either, array, boolean, integer, number, object or string"
The error is fixed when converting the line "type": "file" to "type": "object", but I am not sure if there is a proper way for this situation. Because with this update, the request may not be passed when sending request in Postman.
"parameters": [
{
"in": "body",
"name": "file",
"description": "file",
"required": false,
"schema": {
"type": "array",
"items": {
"type": "file"
}
}
},
...
]
So, how can I fix the problem in Postman?
The problem is not with Postman, but with the API definition. "type": "file" is not a valid type value for use in schemas and body parameters, this type can only be used in in: formData parameters.
On the other hand, I do not add file while trying to test my app via Postman. For this reason, I just want to suppress the errors
In this case you could change "type": "file" to "type": "string" to suppress import errors. Or remove the entire problematic operation from the API definition.
How to properly define file uploads in OpenAPI
The API definition is trying to describe uploading of a file array - but this is not supported in OpenAPI 2.0 (swagger: '2.0'). OAS2 only supports upload of individual named files via multipart/form-data, in which case the API definition would look like this:
{
"swagger: "2.0",
...
"paths": {
"/something": {
"post": {
"consumes": [
"multipart/form-data"
],
"parameters": [
{
"in": "formData",
"name": "file1",
"type": "file" // A single file sent via form field "file1"
},
{
"in": "formData",
"name": "file2",
"type": "file" // Another file sent via form field "file2"
}
]
...
}
Uploading an array of files is supported in OpenAPI 3 though:
{
"openapi": "3.0.0",
...
"paths": {
"/something": {
"post": {
"requestBody": {
"content": {
"multipart/form-data": {
"schema": {
"type": "object",
"properties": {
"file": {
"type": "array",
"items": {
"type": "string",
"format": "binary"
}
}
}
}
}
}
},
...
}
}
}
}
I am new in swagger and want to deploy an API which is having query string. This is the API I am getting encoded URL after passing the parameter in the GET method.
API URL with Parameter should be:-
baseurl/v1/auth/getOTP?email=somename#email.com
but I am getting something like:-
baseurl/v1/auth/getOTP?email=somename%40email.com
what I have tried is:-
"/auth/getOTP": {
"get": {
"tags": [
"pet"
],
"summary": "",
"description": "",
"operationId": "findPetsByStatus",
"produces": [
"application/json",
"application/xml"
],
"parameters": [
{
"name": "email",
"in": "path",
"description": "",
"required": true,
"type": "string",
}
],
"responses": {
"200": {
"description": "successful operation",
"schema": {
"type": "array",
"items": {
"$ref": "#/definitions/Pet"
}
}
},
"400": {
"description": "Invalid value"
}
},
"security": [
{
"petstore_auth": [
"write:pets",
"read:pets"
]
}
]
}
},
Swagger OpenAPI has Specified: in this GitHub Issue-1840, It is specifically disallowed on in: path parameters for the same reason they don't allow optional path parameters, e.g. {/foo} By having variable path segments it become difficult to resolve a URL to an operation.
If you want to use some kind of hack then follow this GitHub Issue-230.
If you really needed then Its support in in: query parameters, as below,
The allowReserved keyword specifies whether the reserved characters :/?#[]#!$&'()*+,;= in parameter values are allowed to be sent as they are, or should be percent-encoded. By default, allowReserved is false, and reserved characters are percent-encoded.
Here you need to set it to true,
"parameters": [
{
"name": "email",
"in": "query",
"description": "",
"required": true,
"type": "string",
"allowReserved": true
}
],
Look at the Example Swagger Describing Parameters
and For more details follow Swagger Serialization.
I have this definition in a swagger document:
"/myEndpoint": {
"post": {
"summary": "handle",
"operationId": "handleUsingGET",
"produces": ["application/json", "application/vnd.spring-boot.actuator.v2+json"],
"parameters": [{
"in": "body",
"name": "body",
"description": "body",
"required": false,
"schema": {
"type": "object",
"additionalProperties": {
"type": "string"
}
}
}
],
"responses": { ... }
}
I need to create a request with a body but I'm not sure how to do that with this schema definition. I have read this question so I know that additionalProperties is used to represent a Dictionary. But there is no property name or anything specified here, so can we say any key-value pairs would be valid to sent in the body? Or is this definition not complete?
This is the description of a certain parameter I have:
{
"name": "myParam",
"description": "My param description",
"required": true,
"paramType": "query",
"type": "string",
"defaultValue":"myValue"
}
The defaultValue is the only value the parameter can have, so is there a way to declare this? Seen in the context of the swagger-ui, I need the parameter's textbox to be read-only. I'm using swagger 1.2.
Thanks
The proper way to declare this would be:
{
"name": "myParam",
"description": "My param description",
"required": true,
"paramType": "query",
"type": "string",
"enum": [ "myValue" ]
}
The "enum" property sets the possible values. Once you set a single value to it, that's the only one that could be used and that would be available in the UI for the user to choose from.
I'm a bit late to the game but with OpenAPI 3.1 you can do the following:
defaultValue:
type: string
const:
- myValue
You can also use 'pattern' of the string to avoid the enum - this could look better in Swagger:
{
"openapi": "3.0.0",
"components": {
"schemas": {
"object": {
"type": "object",
"required": [
"myParam"
],
"properties": {
"myParam": {
"type": "string",
"pattern": "onlyAllowedValue$"
}
}
}
}
}
}