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
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
Using Open API 3.0.1, I'm trying to describe a query parameter of type "integer", lets say we call it ids, that can be alone or can be an array.
For example:
/my-endpoint?ids=111
or
/my-endpoint?ids=111&ids=222
I did try:
- name: ids
in: query
required: false
schema:
type: array
items:
type: integer
And I understand that style: form and explode: true are the default.
But when I validate this with actual requests (I use express-openapi-validate which is a wrapper around Ajv), I get those errors:
/my-endpoint?ids=111
"Error while validating request: request.query.ids should be array"
/my-endpoint?ids=111&ids=222&ids=333
"Error while validating request: request.query.ids[0] should be integer"
And If I use "string" instead of "integer":
- name: ids
in: query
required: false
schema:
type: array
items:
type: string
/my-endpoint?ids=111
"Error while validating request: request.query.ids should be array"
/my-endpoint?ids=111&ids=222&ids=333
Valid!
How should I describe this ids parameter, which must be integer values?
UPDATE: I now understand that any query parameters will be a string when deserialized by an Express server (which I use). But I'm still unable to have a single element array to work!
After the comment from #Helen, I did try another validation library, express-openapi-validator and now it works well with:
- name: ids
in: query
required: false
style: form
explode: true
schema:
type: array
items:
type: integer
With express-openapi-validate, the only way I've been able to make it work is using:
- name: ids
in: query
required: false
schema:
anyOf:
- type: array
items:
type: string
pattern: '^\d+$'
- type: string
pattern: '^\d+$'
So I suggest you use express-openapi-validator with an Express server.
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}
Is there way to define enum list entry as read only? Now I have
type: object
description: |
VISA card
properties:
id:
type: integer
description: Internal ID of the card.
example: 1
minimum: 1
readOnly: true
status:
type: string
required: true
description: Current status of the card.
enum:
- STATUS_ENABLED
- STATUS_DISABLED
- STATUS_DELETED # <-- I Want this to be read only!
Now in patch operation I don't want to redefine above, but instead use it like:
requestBody:
description: VISA card data to be updated.
required: true
content:
application/json:
schema:
$ref: ../../index.yaml#/components/schemas/VisaCard
However, the API behind doesn't allow the status to be set to STATUS_DELETED. How to do this?
EDIT:
To clarify, PATCH should only be able to use STATUS_ENABLED and STATUS_DISABLED.
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.