I've described a param within an OpenAPI 3 spec as
review_requests:
get:
tags:
- dashboard
operationId: reviewRequests
parameters:
- name: page
in: query
default: 0
description: Page number
schema:
type: integer
responses:
200:
description: OK
After compilation I see that the default value is missing from Java code and the param is actually described like:
#Valid #RequestParam(value = "page", required = false) Integer page
and instead of 0 I receive null if the param is not supplied in GET request.
As far as I understand it should be
#Valid #RequestParam(value = "page", required = false, defaultValue = "0") Integer page
Is it a bug or am I doing something wrong?
Finally I've found the solution: in OpenAPI 3.x, the default value must be specified within the parameter's schema. In other words instead of
parameters:
- name: page
in: query
default: 0
description: Page number
schema:
type: integer
it should be
parameters:
- name: page
in: query
description: Page number
schema:
type: integer
default: 0
Related
I have a query parameter defined in the OpenAPI 3 spec as follows:
parameters:
- in: query
name: categories
schema:
type: array
items:
type: string
enum:
- category1
- category2
style: form
explode: false
The expectation is that if I use the "Try it out!" feature and select both category1 and category2, the URL formed should contain:
?categories=category1,category2
However, instead SwaggerUI forms that part of the URL as follows:
?categories=category1&categories=category2
Thus, it seems that SwaggerUI is treating the parameter as though explode is set to true.
How can I get SwaggerUI to go with the comma-separated formulation as that's what the server is expecting?
The issue was that the explode and style properties should have been placed at the same level as schema, not nested inside of it.
parameters:
- in: query
name: categories
style: form
explode: false
schema:
type: array
items:
type: string
enum:
- category1
- category2
I am getting the error below:
Declared path parameter "imageId" needs to be defined as a path
parameter at either the path or operation level
This is the snapshot of my swagger definition
'/api/v1/images/{unitnumber}/{type}/{imageId}':
delete:
tags:
- Images
summary: 'Summary'
description: "Description"
operationId: DeleteImage
consumes: []
produces:
- application/json
parameters:
- name: unitnumber
in: path
required: true
type: string
- name: type
in: path
required: true
type: string
- name: imageId
in: query
required: false
type: string
responses:
'400':
description: Bad Request
schema:
$ref: '#/definitions/ErrorResponse'
'401':
description: Unauthorized
schema:
type: string
'500':
description: Server Error
schema:
$ref: '#/definitions/ErrorResponse'
I only can get rid of the error if I take the imageId and changing to path instead query which is not the intention
- name: imageId
in: path
required: true
type: string
Any idea of what I need to change to have this working?
The path string /api/v1/images/{unitnumber}/{type}/{imageId} means that imageId is a path parameter so it must be in: path.
If imageId is supposed to be a query parameter, as in /api/v1/images/{unitnumber}/{type}?imageId=..., you need to change the path string to /api/v1/images/{unitnumber}/{type}. Query parameters should not be mentioned in paths, they are defined in the parameters section alone.
You have to declare a query parameter using a question mark as follows:
/api/v1/images/{unitnumber}/{type}/{?imageId}
I use swagger ui with swaggerapi/swagger-ui docker image. I try to use parameters defined in components in one of my paths, but that doesn't work. Where is the problem ?
In my index.yaml file
components:
...
parameters:
Pagination:
- in: query
name: page
schema:
type: integer
required: false
description: The page to go to
- in: query
name: per_page
schema:
type: integer
required: false
description: The number of items per page
...
In my path file
parameters:
$ref: '../index.yaml#/components/parameters/Pagination'
Thank you for any help
OpenAPI lets you $ref individual parameters, but not a group of parameters. So if you have several common parameters, you need to create separate definitions for them in the components/parameters section. Also, required is a parameter attribute and not a schema attribute:
components:
parameters:
pageParam: # <-----
in: query
name: page
schema:
type: integer
required: false # <-----
description: The page to go to
perPageParam: # <-----
in: query
name: per_page
schema:
type: integer
required: false # <-----
description: The number of items per page
Then, in your path file, use:
parameters:
- $ref: '../index.yaml#/components/parameters/pageParam'
- $ref: '../index.yaml#/components/parameters/perPageParam'
I'm documenting an API on swagger.io. When I try to define session_token as a required string property in the header, I get the error:
My definition matches the sample in the documentation so I'm not sure what
s causing the issue.
Snippet
/customerVerifyLogin:
post:
summary: Validate verification code sent to authenticate login. Returns session_token
parameters:
- name: Authorization
in: header
type: string
required: true
default: Basic YWRtaW46WDRCbzViWnZTamlXU0hoZDFMOGNpUHkyUERzekUwU3I=
- name: session_type
in: header
type: string
enum:
- android
- ios
required: true
- name: VerificationCode
in: body
type: string
required: true
description:
schema:
type: object
properties:
phone:
type: string
description: The mobile number to which the verification was sent.
device_id:
type: string
description: ID that uniquely identifies the device
code:
in: body
type: integer
format: int32
required: true
description: Verification code to be validated.
responses:
200:
description: Customer logged-in successfully.
schema:
$ref: '#/definitions/Customer'
tags:
- Verification
- Login
a couple errors in your document:
VerificationCode shows type: string and schema:. For a body param (in: body), you can only use schema. Just delete the type: string.
Your definition for the property code has some unwanted fields:
Remove in: body. That's probably a copy/paste error
Remove required: true. That's not the correct way to say a property is required, move it to a sibling of the properties object like such:
required:
- code
properties:
code:
# the rest of your definition
I'm trying to figure out how to use top level parameters and then, at the operation level,use a $ref to refer to the definition that was declared at the top level object.
Here is what the YAML looks like but when I try this I get an empty parameter displayed. Anyone know the correct syntax for this?
swagger: '2.0'
info:
version: 0.1.0
title: Customer API
parameters:
index:
name: index
in: query
description: Specifies the offset of the first item to be returned. The default value is 0, which starts at the beginning.
type: integer
default: 0
minimum: 0
paths:
/customers:
get:
parameters:
- $ref: '#/parameters/index'
responses:
200:
description: List all customers
schema:
$ref: '#/definitions/Customers'
definitions:
Customer:
properties:
name:
type: string
id:
type: integer
format: int32
Customers:
properties:
startIndex:
type: integer
itemsPerPage:
type: integer
totalResults:
type: integer
entries:
type: array
$ref: Customer
The support for this has yet to be implemented in swagger-ui. See https://github.com/swagger-api/swagger-ui/issues/621.