# GET verb version of the "GetClientsForGadget" method from the original ASMX Service
/clients/ProspectClient/roleandcstbased/{OrgNmFilter}/{SortNm}?{UserName}:
get:
tags:
- Client
summary: Merging of GetClientsforGadget and GetClientsForUser
operationId: ClientsForGadgetGET
parameters:
- name: OrgNmFilter
in: path
description: Organization Name Filter
required: true
type: string
- name: SortNm
in: path
description: Sort Field
required: true
type: string
- name: UserName
in: query
description: User's Identity
required: false
type: string
responses:
200:
description: Output results for GetClientsForGadget endpoint
schema:
$ref: '#/definitions/ClientOutput'
Swagger is giving me not a valid parameter definition for this query parameter. If I remove all references to Username in the path and parameter definition, no issues.
According to the Swagger Specification, I believe I'm using query parameters right, but somehow it's not.
Realized the issue was in path. The path does not need to include the query parameter.
/clients/ProspectClient/roleandcstbased/{OrgNmFilter}/{SortNm}?{UserName}:
/clients/ProspectClient/roleandcstbased/{OrgNmFilter}/{SortNm}:
It only needs the query to be defined in parameters. Otherwise bugs the whole thing out.
Related
I have a swagger 2.0 resource defined below. How can I make "param1 or param2" required? Caller has to pass either param1 or param2.
/some/res:
put:
summary: some resource
responses:
200:
description: Successful response
schema:
$ref: '#/definitions/SomeResponse'
parameters:
- name: param1
type: string
description: param1
in: formData
required: false
- name: param2
type: string
description: param2
in: formData
required: false
OpenAPI (fka Swagger) Specification does not support conditional or mutually exclusive parameters (of any type).
There is an open feature request:
Support interdependencies between query parameters
The specific scenario in this question – a POST/PUT/PATCH request with a form-data body that contains either param1 or param2 – can be defined using OpenAPI 3.0 and oneOf:
openapi: 3.0.0
...
paths:
/some/res:
put:
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
oneOf:
- type: object
properties:
param1:
type: string
required:
- param1
additionalProperties: false
- type: object
properties:
param2:
type: string
required:
- param2
additionalProperties: false
Note for Swagger UI users: form-data UI and example rendering for oneOf schemas are not available for OpenAPI 3.0 definitions yet.
In the Parameter Dependencies section of the Describing Parameters Swagger docs:
Swagger does not support parameter dependencies and mutually exclusive parameters. There is an open feature request at https://github.com/OAI/OpenAPI-Specification/issues/256.
As of June 2017, that issue had 21 upvotes, making it the third most upvoted issue in the project.
The Swagger specification does not support conditional requirement or inclusion/exclusion of parameters.
What I would suggest is to state clearly in the description your rules for inclusion/exclusion of query parameters. Then using a validation framework, which depends on your language (i.e. javax.validation for Java, restify-validation for restify, etc.), validate the parameters accordingly.
You can use a simple trick. Use different requests with the same route but define different "home made" query parameters using "path" type instead of the "query".
For some interdependent logic between parameters, put the logic in your API and define specific responses based on correct/uncorrect requests. You can also protect the URL definition on the client-side, but let the stuff where they belong.
/myUrl/myRoute/?queryPara1={query1}?queryPara2={query2}:
get:
parameters:
- in: path
name: query1
schema:
type: string
- in: path
name: query2
schema:
type: string
/myUrl/myRoute/?queryPara3={query3}?queryPara4={query4}:
get:
parameters:
- in: path
name: query3
schema:
type: string
- in: path
name: query4
schema:
type: string
Can not get how to use reference of string type with enum values in array parameter.
I can make reference in items key and it is working, but Swagger produce error: Not a valid parameter definition
Web UI generates interface, but it have textarea instead of multiselect box I expected.
What is the proper way to do it?
My code:
swagger: '2.0':
paths:
/test:
get:
parameters:
- in: origin
name: status
description: Origin
required: false
schema:
type: array
items:
$ref: '#/definitions/Origin'
collectionFormat: pipes'
definitions:
Origin:
type: string
description: Campaign origin
enum:
- one
- two
externalDocs:
description: Find out more about Swagger
url: http://swagger.io
host: virtserver.swaggerhub.com
basePath: /
Array parameters with items containing $ref are not supported in OpenAPI/Swagger 2.0. But it looks like this will be possible in the next version, 3.0. For now there are a couple of workarounds, see below.
Your spec also has some other issues:
in: origin is not valid. The in keyword specifies the parameter location (path, query, header, etc.) and only accepts certain values as per the OpenAPI/Swagger spec. I guess you meant in: query or in: header.
Typos (or copy-paste errors?): swagger: '2.0': has an extra : at the end and collectionFormat: pipes' has an extra ' at the end.
One solution for having an array parameter containing enum values is to define the enum inline:
parameters:
- in: query
name: status
description: Origin
required: false
type: array
collectionFormat: pipes
items:
type: string
enum:
- one
- two
Another solution (found here) is to use YAML anchors to reference the enum. This is a feature of YAML where you can mark a key with &anchor-name and then further down use *anchor-name to reference that key's value.
definitions:
Origin:
type: string
description: Campaign origin
enum: &origin
- one
- two
paths:
/test:
get:
parameters:
- in: query
name: status
description: Origin
required: false
type: array
collectionFormat: pipes
items:
type: string
enum: *origin
One option is to define a parameter and make a reference to that: (I had an issue with using reference ($ref:) within a query definition)
paths:
/path:
get:
operationId: controllers.controller
parameters:
**- $ref: '#/parameters/SPEC'**
parameters:
SPEC:
I am starting a REST service, using Swagger Codegen. I need to have different responses for different parameters.
Example: <baseURL>/path can use ?filter1= or ?filter2=, and these parameters should produce different response messages.
I want my OpenAPI YAML file to document these two query params separately. Is this possible?
It is not supported in the 2.0 spec, and not in 3.0 either.
Here are the corresponding proposals in the OpenAPI Specification repository:
Accommodate legacy APIs by allowing query parameters in the path
Querystring in Path Specification
If you're still looking, I found out a way around this problem. It's a bit of a hack, but it works.
Basically, you can have two definitions to the same path by adding a slash (/) in the URL.
That way, you can set a response for <baseURL>/path with the ?filter1= parameter and set another response for <baseURL>//path with the ?filter2= parameter. It's also important that you give an unique operationId for each of the definitions.
paths:
/path/you/want:
get:
summary: Test
operationId: get1
parameters:
- name: filter1
type: string
in: path
required: true
responses:
200:
description: Successful response
schema:
$ref: '#/definitions/SomeResponse'
/path/you//want:
get:
summary: Another test
operationId: get2
parameters:
- name: filter2
type: string
in: path
required: true
responses:
200:
description: Successful response
schema:
$ref: '#/definitions/SomeOtherResponse'
I tried this with a path parameter and it worked just fine!
In swagger defining location,type explicitly is what defines these variables.
You have all the required fields to avoid collision of variables, for a json body you have to reference a declaration or use an example schema as shown below. For my case I have used a schema example rather than a declaration reference
/auth/account/password/reset/{userId}/{resetToken}:
post:
consumes:
- application/json
parameters:
- in: path
name: userId
type: string
required: true
- in: path
type: string
name: resetToken
required: true
- in: header
name: authorization
required: true
type: string
- in: body
name: body
required: true
schema:
type: object
example:
password: password
confirmPassword: password
responses:
"200":
description: OK
In Swagger you can add ? to make endpoints different.
i.e. /articles and /articles?:
When using ? in Swagger editor you will see error:
However on your final Swagger page there will be mark VALID
Additional information:
Remember about unique operationId for duplicated entries
Is it possible to group multiple parameters to reference them in multiple routes?
For example I have a combination of parameters which I need in every route. They are defined as global parameters. How can I group them?
I think about a definition like this:
parameters:
MetaDataParameters:
# Meta Data Properties
- name: id
in: query
description: Entry identification number
required: false
type: integer
- name: time_start
in: query
description: Start time of flare
required: false
type: string
- name: nar
in: query
description: Active region number
required: false
type: string
And then reference the whole group in my route:
/test/:
get:
tags:
- TEST
operationId: routes.test
parameters:
- $ref: "#/parameters/MetaDataParameters"
responses:
200:
description: OK
Is this possible with Swagger 2.0?
This is not possible with Swagger 2.0, OpenAPI 3.0 or 3.1. I've opened a feature request for this and it is proposed for a future version:
https://github.com/OAI/OpenAPI-Specification/issues/445
you can point your $ref to middle .yaml file, like this:
//middle.yaml <-----
- $ref: 'Defaul.yaml#/components/parameters/meta_id'
- $ref: 'Defaul.yaml#/components/parameters/meta_time_start'
- $ref: 'Default.yaml#/components/parameters/meta_nar'
your Default.yaml file should be like this:
//Default.yaml <-----
components:
parameters:
meta_id:
name: id
in: query
description: Entry identification number
schema:
type: integer
example: 1
meta_time_start:
name: time_start
in: query
schema:
type: string
finally, your main file should be looks like this:
/test/:
get:
tags:
- TEST
operationId: routes.test
parameters:
$ref: "../parameters/middle.yaml" <---- external yaml file
responses:
200:
description: OK
NOTE: your $ref should be without -. like in my example
I have a swagger 2.0 resource defined below. How can I make "param1 or param2" required? Caller has to pass either param1 or param2.
/some/res:
put:
summary: some resource
responses:
200:
description: Successful response
schema:
$ref: '#/definitions/SomeResponse'
parameters:
- name: param1
type: string
description: param1
in: formData
required: false
- name: param2
type: string
description: param2
in: formData
required: false
OpenAPI (fka Swagger) Specification does not support conditional or mutually exclusive parameters (of any type).
There is an open feature request:
Support interdependencies between query parameters
The specific scenario in this question – a POST/PUT/PATCH request with a form-data body that contains either param1 or param2 – can be defined using OpenAPI 3.0 and oneOf:
openapi: 3.0.0
...
paths:
/some/res:
put:
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
oneOf:
- type: object
properties:
param1:
type: string
required:
- param1
additionalProperties: false
- type: object
properties:
param2:
type: string
required:
- param2
additionalProperties: false
Note for Swagger UI users: form-data UI and example rendering for oneOf schemas are not available for OpenAPI 3.0 definitions yet.
In the Parameter Dependencies section of the Describing Parameters Swagger docs:
Swagger does not support parameter dependencies and mutually exclusive parameters. There is an open feature request at https://github.com/OAI/OpenAPI-Specification/issues/256.
As of June 2017, that issue had 21 upvotes, making it the third most upvoted issue in the project.
The Swagger specification does not support conditional requirement or inclusion/exclusion of parameters.
What I would suggest is to state clearly in the description your rules for inclusion/exclusion of query parameters. Then using a validation framework, which depends on your language (i.e. javax.validation for Java, restify-validation for restify, etc.), validate the parameters accordingly.
You can use a simple trick. Use different requests with the same route but define different "home made" query parameters using "path" type instead of the "query".
For some interdependent logic between parameters, put the logic in your API and define specific responses based on correct/uncorrect requests. You can also protect the URL definition on the client-side, but let the stuff where they belong.
/myUrl/myRoute/?queryPara1={query1}?queryPara2={query2}:
get:
parameters:
- in: path
name: query1
schema:
type: string
- in: path
name: query2
schema:
type: string
/myUrl/myRoute/?queryPara3={query3}?queryPara4={query4}:
get:
parameters:
- in: path
name: query3
schema:
type: string
- in: path
name: query4
schema:
type: string