I am trying to define an API using Swagger 2.0. In my model I have some object which have optional attributes, so I am trying to insert the Swagger tag "required:false".
When I insert the "required" tag, I am getting an error in the editor and I can't figure why..
My Swagger definition is:
definitions:
Error:
type: object
properties:
code:
type: integer
message:
type: string
fields:
type: string
This is perfectly working. Now I want to specify that the 'message' parameter (for example) is optional. So I try the following:
definitions:
Error:
type: object
properties:
code:
type: integer
message:
type: string
required: false
fields:
type: string
And now I have an error in the Swagger Editor:
Swagger Error
Expected type array but found type boolean
Error details are:
Details
Object
code: "INVALID_TYPE"
message: "Expected type array but found type boolean"
path: Array [5]
0: "definitions"
1: "Error"
2: "properties"
3: "message"
4: "required"
level: 900
type: "Swagger Error"
description: "Expected type array but found type boolean"
lineNumber: 41
Lines:
[40] message:
[41] type: string
[42] required: false
Did someone have an idea about what I am doing wrong ?
If only code and fields are mandatory you can do something like:
definitions:
Error:
type: object
required: [code, fields]
properties:
code:
type: integer
message:
type: string
fields:
type: string
Related
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 defined in swagger editor the following object(amountInCurrency):
pot:
type: object
properties:
potId:
type: string
name:
type: string
amount:
type: number
status:
type: string
lastChangeTimestamp:
type: string
amountInCurrency:
type: object
items:
$ref: '#/definitions/amountInCurrency'
and
amountInCurrency:
type: object
properties:
currency:
type: string
amount:
type: number
I got in that items currency and amount. however on swagger visualization i see amountInCurrency as an empty map. any idea why?
i would expect to see the currency and amount fields describe in it
-- edit:
if I change the AmountInCurrency type from object to array I do see the internal docs within the doc
doing this:
amountInCurrency:
type: array
items:
$ref: '#/definitions/amountInCurrency'
The amountInCurrency property definition does not look right - it mixes type: object with an array-specific keyword items.
If the amountInCurrency property is an array of amountInCurrency objects, use type: array instead:
amountInCurrency:
type: array # <-----
items:
$ref: '#/definitions/amountInCurrency'
If the amountInCurrency property is an object (an instance of the amountInCurrency object), use $ref like so:
amountInCurrency:
$ref: '#/definitions/amountInCurrency'
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 have an API that looks similar to
public Optional<Status> getStatus
But cannot figure out how the swagger spec definition should look. The swagger.io editor error message for the following doesn't mean much:
get:
...
responses:
'200':
description: OK
schema:
$ref: '#/definitions/Status'
definitions:
Status:
properties:
type: string
description: Blah
enum:
- UNKNOWN
Was just the outer 'properties' property causing the problem (as string not object):
definitions:
Status:
type: string
description: Blah
enum:
- UNKNOWN
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.