I am creating API documentation utilizing Swagger UI. I have many errors that say "Not a valid parameter definition" and I don't know why. Can anyone tell what or why this is happening? I include a section of the code and a picture with the line numbers and the error descriptions.
swagger example
#sys_application
/api/application/add:
post:
description: Adds specified application(s).
parameters:
- name: name
in: body
description: name of the application
required: true
type: string
- name: appId
in: body
description: application id
required: true
type: string
- name: icon
in: body
description: application icon
required: true
type: string
- name: state
in: body
description: current state of the application
required: true
type: string
- name: profileRoute
in: body
description: embedded profile route that is displayed within the map app
required: true
type: string
- name: type
in: body
description: type of the application
required: true
type: string
- name: permissions
in: body
description: user permissions for application
required: false
type: string
- name: subscriptions
in: body
description: application subscriptions
required: false
type: string
swagger error
when you use in: body, the spec expects a schema element, such as:
name: user
in: body
schema:
type: object
properties:
userId:
type: string
If you're not using a body parameter, you are expected to use a primitive value, such as type: string.
Related
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 need to define two fields named "description" and "type" in object with swagger 2.0,below is example,
description:
type: string
description: ''
type:
type: string
description: ''
However,an error "..Duplicated mapping key..." thrown out.Is there any solution to resolve this error since the field names are specified?
Checked in this editor and this object definition is working (based on some example yamls):
newPet:
type: object
properties:
id:
type: integer
format: int64
description:
type: string
description: ''
type:
type: string
description: ''
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 have an object that has a property that is an object whose type would be one of list of types. All my attempts have been rejected by Swagger Editor with the following error:
Data does not match any schemas from 'anyOf'
Jump to line 43
Details
Object
code: "ANY_OF_MISSING"
message: "Data does not match any schemas from 'anyOf'"
path: Array [7]
inner: Array [2]
level: 900
type: "Swagger Error"
description: "Data does not match any schemas from 'anyOf'"
lineNumber: 43
The full swagger specification file is as follows (the field in question is DataSetsInquiryRsp.dataSets.dataSet):
swagger: '2.0'
info:
title: My API
description: My Awesome API
version: 1.0.0
paths:
/dataSetsInquiry:
get:
description: Retrieve one or more data-sets.
parameters:
- name: ids
in: query
description: List of identifiers of requested data-sets.
required: true
type: array
items:
type: string
responses:
'200':
description: Requested data-sets.
schema:
$ref: '#/definitions/DataSetsInquiryRsp'
default:
description: Unexpected error
schema:
$ref: '#/definitions/Error'
definitions:
DataSetsInquiryRsp:
type: object
additionalProperties: false
properties:
sessionIdentifier:
description: Identifier of the secure session with the server.
type: number
dataSets:
type: object
additionalProperties: false
properties:
id:
type: string
dataSet:
type: array
items:
oneOf:
- $ref: '#/definitions/Customer'
- $ref: '#/definitions/Merchant'
Customer:
type: object
additionalProperties: false
properties:
firstName:
description: First name of the customer
type: string
lastName:
description: Last name of the customer
type: string
Merchant:
type: object
additionalProperties: false
properties:
code:
description: Code the Merchant.
type: string
name:
description: Name of the Merchant.
type: string
Well, the issue is simply the fact that Swagger doesn't support oneOff. In fact, Swagger supports a subset of Json-Schema and add a few things (datatype file for instance).
What is bad here is the error returned by Swagger. It doesn't help match. And this is the case of all Json-Schema validators I have worked with so far: is-my-json-valid, jsen.