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.
Related
Is there any way to set up example for request body in swagger 2.0?
My scheme is the same like in https://petstore.swagger.io/
My json param:
"parameters": [
{
"in": "body",
"name": "body",
"description": "Pet object that needs to be added to the store",
"required": true,
"schema": {
"$ref": "#/definitions/Pet"
},
"x-example": "x-example": "{\r\n\"id\":123123123123123123,\r\n\"category\":{\r\n\"id\":44,\r\n\"name\":\"A12312312312312AA\"\r\n},\r\n\"name\":\"X123123123123XX\",\r\n\"photoUrls\":[\r\n\"st123123123ring\"\r\n],\r\n\"tags\":[\r\n{\r\n\"id\":0,\r\n\"name\":\"str123123ing\"\r\n}\r\n],\r\n\"status\":\"avai123123lable\"\r\n}""
}
],
I tried everything to setup my own example.
x-example:
default/(application/json):
and so on. No result.
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?
I am using Swagger Editor to work on a JSON Swagger 2.0 API definition. I have reduced my definition to a minimum example of the problem I am experiencing. The problem occurs when I use a reference object to define a path parameter that is shared between multiple endpoints.
Example endpoints:
/my-api/{id}/some-thing
/my-api/{id}/some-other-thing
Since these id parameters are defined the same way, I abstracted them to the parameters section of the JSON file, and included them with "$ref": "#/parameters/testObjectId".
The Swagger reduced definition shows this:
{
"swagger": "2.0",
"info": {
"title": "Test Service",
"description": "REST API for TestObjects",
"version": "1.0.0"
},
"host": "api.not-a-real-url.com",
"schemes": [
"https"
],
"basePath": "/api/test-objects",
"produces": [
"application/hal+json"
],
"consumes": [
"application/json"
],
"paths": {
"/{id}": {
"get": {
"operationId": "getTestObject",
"summary": "Get a TestObject resource referenced by slug string ID",
"security": [],
"parameters": [
{
"$ref": "#/parameters/testObjectId"
}
],
"responses": {
"200": {
"description": "Success",
"schema": {
"type": "object",
"properties": {}
}
},
"default": {
"description": "Error",
"schema": {
"type": "object",
"properties": {}
}
}
}
}
}
},
"parameters": {
"testObjectId": {
"name": "id",
"in": "path",
"required": true,
"type": "string",
"format": "slug",
"description": "Immutable, unique identifier of a TestObject"
}
},
"definitions": {
}
}
But when this is rendered in Swagger, I get the following error:
Errors
Semantic error at paths./{id}
Declared path parameter "id" needs to be defined as a path parameter at either the path or operation level
The problem is that id is actually defined, only it appears that the check which throws this error is occurring before the $ref is included. The Swagger output looks correct.
Further, I have used this approach for about 6 months (as long as I have used Swagger) and I am just now running into the problem for the first time. Is there something I should be doing differently to prevent this error? Am I misusing Swagger by doing it this way?
Your spec is valid. It was a bug introduced in Swagger Editor v.3.2.2, it was fixed in v.3.2.3 (released on January 6, 2018).
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.
I have tried changing the basePath in my json file, which only seems to change the bottom "baseurl" of swagger-UI. I want to get rid of the "Default" that appears as a group title of my swagger-UI. Has anyone been able to fix this problem? I am using Swagger ~2.0.
The Default is not a path, it's a tag.
In Swagger 2.0, grouping is done using tags. Each operation can be assigned to zero or more tags. In the UI, any operation that has no tag will end up under the Default group.
"/pet/findByStatus": {
"get": {
"tags": [
"pet"
],
"summary": "Finds Pets by status",
"description": "Multiple status values can be provided with comma seperated strings",
"operationId": "findPetsByStatus",
"consumes": [
"application/xml",
"application/json",
"multipart/form-data",
"application/x-www-form-urlencoded"
],
"produces": [
"application/xml",
"application/json"
],
"parameters": [
{
"name": "status",
"in": "query",
"description": "Status values that need to be considered for filter",
"required": false,
"type": "array",
"items": {
"type": "string"
},
"collectionFormat": "multi",
"default": "available",
"enum": [
"available",
"pending",
"sold"
]
}
],
"responses": {
"200": {
"description": "successful operation",
"schema": {
"type": "array",
"items": {
"$ref": "#/definitions/Pet"
}
}
},
"400": {
"description": "Invalid status value"
}
},
"security": [
{
"petstore_auth": [
"write:pets",
"read:pets"
]
}
]
}
}
You can see the operations has a tags property with the value of "pet", and that operation would be grouped under that header.