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'
Related
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
How can I reference from one description of an component to another?
comparam01:
in: query
name: comparam01
schema:
type: string
description: |
Any text.
comparam02:
in: query
name: comparam02
schema:
# that's working!
$ref: '#/components/parameters/comparam01/schema'
description:
# Swagger says: Error (should be a string)
$ref: '#/components/parameters/comparam01/description'
I'm reading this: OpenAPI 3.0 Tutorial
If I'm looking on one of the examples, there are some things I can't understand
openapi: 3.0.0
info:
version: 1.0.0
title: Simple API
description: A simple API to illustrate OpenAPI concepts
servers:
- url: https://example.io/v1
components:
securitySchemes:
BasicAuth:
type: http
scheme: basic
security:
- BasicAuth: []
paths:
/artists:
get:
description: Returns a list of artists
parameters:
- name: limit
in: query
description: Limits the number of items on a page
schema:
type: integer
- name: offset
in: query
description: Specifies the page number of the artists to be displayed
schema:
type: integer
responses:
'200':
description: Successfully returned a list of artists
content:
application/json:
schema:
type: array
items:
type: object
required:
- username
properties:
artist_name:
type: string
artist_genre:
type: string
albums_recorded:
type: integer
username:
type: string
'400':
description: Invalid request
content:
application/json:
schema:
type: object
properties:
message:
type: string
# ----- Added lines ----------------------------------------
post:
description: Lets a user post a new artist
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- username
properties:
artist_name:
type: string
artist_genre:
type: string
albums_recorded:
type: integer
username:
type: string
responses:
'200':
description: Successfully created a new artist
'400':
description: Invalid request
content:
application/json:
schema:
type: object
properties:
message:
type: string
# ---- /Added lines ----------------------------------------
Why the response of /get contains: required: username ? what is the meaning of this ?
if I don't want basic authentication, can I remove this line ?
Why do we need to write required: true for the requestBody under the post ? It's not basic that post contains body ?
The answer of your questions are:
Why the response of /get contains: required: username? what is the meaning of this? if I don't want basic authentication, can I remove this line?
Ans: Username is required means it's mandatory, i.e. response must contain this field with some value in it. It's not associated with basic authentication. So, yes you can remove that line if it is not used by the application.
Why do we need to write required: true for the requestBody under the post? It's not basic that post contains body?
Ans: Required: true is not mandatory to write here. It's an optional field and post must have a request body. Yeah, you are right. It's a basic thing that posts must have to contain the request body.
If you can have any confusion further then let me know. Thanks
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'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.