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: ''
Related
How do i use the Swagger models when i have diffrent representations for each model depending on the authorization level.
For example, a country model for an administrator looks like this:
definitions:
Country:
type: object
properties:
id:
type: integer
format: int64
name:
type: string
example: The Netherlands
code:
type: string
example: NL
created_at:
type: string
example: 2017-06-01 13:37:00
updated_at:
type: string
example: 2017-06-01 14:00:00
However, just a regular user model looks like this
definitions:
Country:
type: object
properties:
id:
type: integer
format: int64
name:
type: string
example: The Netherlands
code:
type: string
example: NL
I was considering to place the model definitions in the response like this:
/admin/countries/{countryId}:
get:
tags:
- AdminCountries
summary: Find a country by ID
operationId: adminCountriesGetById
security:
- Bearer: []
parameters:
- in: path
type: integer
format: int64
name: countryId
required: true
responses:
'200':
description: Success
schema:
type: object
properties:
id:
type: integer
format: int64
name:
type: string
example: The Netherlands
code:
type: string
example: NL
created_at:
type: string
example: 2017-06-01 13:37:00
updated_at:
type: string
example: 2017-06-01 14:00:00
I am not really sure if my "solution" is the correct way to handle this.
The upcoming OpenAPI Specification 3.0 will support oneOf to define multiple possible request/response bodies.
In 2.0, the most you can do is to define the administrator-specific properties as optional and use description to document that these properties are returned for administrators ony and not for regular users.
In my API i would like to have a simple model for my collection and a more elaborate model for my individual resource. For example:
a GET request on /libraries should return
BaseLibrary:
type: object
properties:
library_id:
type: string
description: The id of the library
display_name:
type: string
description: Name of the library
href:
type: string
description: The URI linking to this library.
whilst a request to a specific library should return all of the above including an extra parameter books:
So a GET request to libraries/{library_id} should return:
ExtendedLibrary:
type: object
properties:
library_id:
type: string
description: The id of the library
display_name:
type: string
description: Name of the library
href:
type: string
description: The URI linking to this library.
books:
type: array
description: The books in this library
items:
$ref: "#/definitions/books"
I would very much like to not have to define a "BaseLibrary" twice and would want to simple model an additional "ExtendedLibrary" which contains all the responses of a base library and the additional books property.
I tried a lot of different things, with the closest to succes being the following definitions:
definitions:
BaseLibrary:
type: object
properties:
library_id:
type: string
description: The id of the library.
display_name:
type: string
description: Name of the library
href:
type: string
description: The URI linking to this library.
ExtendedLibrary:
type: object
properties:
$ref: "#/definitions/BaseLibrary/properties"
books:
type: array
description: The available books for this library.
items:
$ref: "#/definitions/Book"
However this gives me a "Extra JSON reference properties will be ignored: books" warning and the output seems to ignore this extra property. Is there a clean way to handle my problem? Or am I just going to have to copy paste my whole BaseLibrary model into my ExtendedLibrary model?
As mentioned in the comments section, this may be a duplicate of another question, but it's worth repeating the answer in the context of this particular example. The solution is to use the allOf property in the definition of ExtendedLibrary:
definitions:
Book:
type: object
properties:
title:
type: string
author:
type: string
BaseLibrary:
type: object
properties:
library_id:
type: string
description: The id of the library
display_name:
type: string
description: Name of the library
href:
type: string
description: The URI linking to this library.
ExtendedLibrary:
type: object
allOf:
- $ref: '#/definitions/BaseLibrary'
- properties:
books:
type: array
description: The books in this library
items:
$ref: "#/definitions/Book"
In my experience, Swagger UI visualizes this correctly. When I define an operation response to be ExtendedLibrary Swagger UI shows this example:
{
"library_id": "string",
"display_name": "string",
"href": "string",
"books": [
{
"title": "string",
"author": "string"
}
]
}
Also, Swagger Codegen does the right thing. At least when generating a Java client, it creates an ExtendedLibrary class that correctly extends BaseLibrary.
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.
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
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.