I have the following schema definition:
swagger: '2.0'
...
definitions:
Service:
type: object
properties:
serviceId:
type: string
description: Device or service identification number
example: 1111111111
location:
type: string
description: Location of the service
example: '400 Street name, City State postcode, Country'
I would like to do annotate the location field as deprecated. Is there a way to do this?
The possibility to mark schemas and schema properties as deprecated was added in OpenAPI 3.0:
openapi: 3.0.1
...
components:
schemas:
Service:
type: object
properties:
location:
type: string
description: Location of the service
example: '400 Street name, City State postcode, Country'
deprecated: true # <---------
If you use OpenAPI 2.0 (Swagger 2.0), the only thing you can do is document the deprecation verbally in the property description.
according to documentation it is enough to use deprecated attribute
/pet/findByTags:
get:
deprecated: true
Related
I have an endpoint with query parameters that use square brackets:
GET /info?sort[name]=1&sort[age]=-1
Here, name and age are the field names from my model definition.
How can I write an OpenAPI (Swagger) definition for these parameters?
It depends on which version of OpenAPI (Swagger) you use.
OpenAPI 3.x
The sort parameter can be defined an an object with the name and age properties. The parameter serialization method should be style: deepObject and explode: true.
openapi: 3.0.0
...
paths:
/info:
get:
parameters:
- in: query
name: sort
schema:
type: object
properties:
name:
type: integer
example: 1
age:
type: integer
example: -1
style: deepObject
explode: true
responses:
'200':
description: OK
This is supported in Swagger UI 3.15.0+ and Swagger-Editor 3.5.6+.
Important: The deepObject serialization style only supports simple non-nested objects with primitive properties, such as in the example above. The behavior for nested objects and arrays of objects is not defined.
In other words, while we can define
?param[foo]=...¶m[bar]=...
there's currently no way to define more nested query parameters such as
?param[0][foo]=...¶m[1][bar]=...
or
?param[foo][0][smth]=...&?param[foo][1][smth]=
If you need the syntax for deeply nested query parameters, upvote and follow this feature request:
Support deep objects for query parameters with deepObject style
OpenAPI 2.0 (Swagger 2.0)
sort[name] and sort[age] need to be defined as individual parameters:
swagger: '2.0'
...
paths:
/info:
get:
parameters:
- in: query
name: sort[name]
type: integer
- in: query
name: sort[age]
type: integer
responses:
200:
description: OK
I have a swagger file for an API that is going to reside inside IBM API Connect. I typed it out from an IBM tutorial, and I was trying to replicate what the instructor was doing(he did not provide any source files, so I had to type it out).
The tutorial is available here: https://www.youtube.com/watch?v=hCvUYd67rbI
The guy is copy-pasting the swagger file inside the APIConnect local designer around 21:40.
I took the swagger file and put it into http://editor.swagger.io/ and I got a bunch of parser errors:
Errors
Hide
Parser error duplicated mapping key
Jump to line 31
Semantic error at definitions.shipping.properties.xyz.type
Sibling values are not allowed alongside $refs
Jump to line 86
Semantic error at definitions.shipping.properties.cek.type
Sibling values are not allowed alongside $refs
Jump to line 89
I did some digging, and I did not find a lot of resources for my kind of problem. I double-checked if I typed it out correctly from the tutorial. Maybe it has something to do with an older version of API Connect being used in ths tutorial.
Thanks in advance for anyone who can help.
EDIT:
Sorry, it was a bit late so I was tired, I am adding the source code in the yaml file:
info:
x-ibm-name: logistics
title: logistics
version: 1.0.0
schemes:
- https
basePath: /logistics
consumes:
- application/json
produces:
- application/json
securityDefinitions:
clientIdHeader:
type: apiKey
in: header
name: X-IBM-Client-Id
security:
- clientdHeader: []
x-ibm-configuration:
testable: true
enforced: true
cors:
enabled: true
gateway: datapower-gateway
catalogs:
apic-dev:
properties:
runtime-url: $(TARGET_URL)
properties:
shipping_svc_url:
value: 'http://shipping.think.ibm:5000/calculate'
description: Location of the shipping calculator service
encoded: false
paths:
/shipping:
get:
responses:
'200':
description: 200 OK
schema:
$ref: '#/definitions/shipping'
summary: Calculate shipping costs to a destination zip code
operationId: shipping.calc
parameters:
- name: zip
type: string
required: true
in: query
description: Destination zip code.
/stores:
get:
responses:
'200':
description: 200 OK
schema:
$ref: '#/definitions/store_location'
tags:
- stores
summary: Locate store near zip code
operationId: get.stores
parameters:
- name: zip
type: string
required: true
in: query
definitions:
rates:
properties:
next_day:
type: string
example: '20.00'
two_day:
type: string
example: '17.00'
ground:
type: string
example: '8.00'
required:
- two_day
- next_day
- ground
shipping:
properties:
xyz:
type: string
$ref: '#/definitions/rates'
cek:
type: string
$ref: '#/definitions/rates'
required:
- xyz
- cek
store_location:
properties:
google_maps_link:
type: string
example: 'https://www.google.com/maps?q=34.1030032,-118.4104684'
required:
- google_maps_link
There's typo: securityDefinitions defines clientIdHeader, but security refers to clientdHeader (..ntd.. instead of ..enId..).
"Sibling values are not allowed alongside $refs" is not a syntax error, but rather a warning. It's caused by this line:
definitions:
rates:
properties:
...
shipping:
properties:
xyz:
type: string # <---------------
$ref: '#/definitions/rates'
$ref is a JSON Reference, it works by replacing itself and all sibling attributes with the content the $ref is pointing at. So, the type attribute and any other attributes alongside $ref will be ignored. The warning informs you about this in case there are important attributes alongside $ref -- these attributes need to be moved into the $ref'erenced schema to have effect.
That said, xyz being type: string does not make sense, because rates is an object and not a string.
You should also consider adding type: object to the rates, shipping and store_location definitions to indicate that they are objects.
I define a path that takes MyObject as a parameter.
MyObject has properties for cats and dogs. These have default values.
In swagger-editor, the example doesn't show the default values, but try-it-out does create a MyObject with correct defaults.
In swagger-ui, I can see the defaults under Models, but not in the API. Is there a way to set these defaults ?
swagger: '2.0'
info:
title: pass object with default properties as a parameter
description: etc
version: "Draft 0.1.1"
host: example.com
basePath: /
produces:
- application/json
paths:
/myobject:
post:
summary: |
post an object.
parameters:
- name: myObject
in: body
required: true
schema:
type: array
items:
$ref: '#/definitions/MyObject'
responses:
200:
description: OK
definitions:
MyObject: # move to/models/model.yml
type: object
description: Contains default properties
required:
- cats
- dogs
properties:
cats:
type: number
default: 9
dogs:
type: string
default: "fido"
Your usage of default is wrong. You probably want example instead.
default is only used with optional fields and is handled on the server side. That is, if the client does not supply a value in the payload, the server will use the default value.
Consider this User model:
definitions:
User:
type: object
required:
- username
properties:
username:
type: string
role:
type: string
enum:
- user
- poweruser
- admin
default: user
The role property is optional and defaults to user. So, if the client sends the payload without role:
{
"username": "bob"
}
the server will assume role=user.
In your case, it looks like you want to provide example values for the fields. This is what the example keyword is for:
definitions:
MyObject:
type: object
description: Contains default properties
required:
- cats
- dogs
properties:
cats:
type: number
example: 9 # <---
dogs:
type: string
example: fido # <---
It seems like there are 2 kinds of defaults:
server-side: variable is not required and server will assume a value for it if it is not given definition from OpenApi v3.0 spec
client side: variable is required and must be only one value (for example headers)
For a client-side default, we can define it by setting required=True and enum to the only allowed value. See this example below:
swagger: "2.0"
info:
title: "some api"
description: "a description"
version: "1.0.0"
host: "example.com"
basePath: "/api"
schemes:
- "http"
paths:
/myobject:
post:
summary: |
post an object.
parameters:
- name: myObject
in: body
required: true
schema:
type: array
items:
$ref: '#/definitions/MyObject'
responses:
200:
description: OK
definitions:
MyObject:
type: object
description: Contains default properties
required:
- cats
- dogs
properties:
cats:
type: number
enum:
- 9
dogs:
type: string
enum:
- fido
And you can see it work in the swagger-editor here: https://editor.swagger.io/
The default parameter is a bit confusing because swagger 2.0 initially described the default parameter without specifying a server or client reference frame.
Swagger 2.0 spec
Defines schema default as
default (Unlike JSON Schema, the value MUST conform to the defined type for the Schema Object)
OpenAPI v3.0 spec
default - The default value represents what would be assumed by the consumer of the input as the value of the schema if one is not provided. Unlike JSON Schema, the value MUST conform to the defined type for the Schema Object defined at the same level. For example, if type is string, then default can be "foo" but cannot be 1.
I'm using http://editor.swagger.io to design an API and I get an error which I don't know how to address:
Schema error at paths['/employees/{employeeId}/roles'].get.parameters[0]
should NOT have additional properties
additionalProperty: type, format, name, in, description
Jump to line 24
I have other endpoints defined in a similar way, and don't get this error. I wondered if I had some issue with indentation or unclosed quotes, but that doesn't seem to be the case. Google also did not seem to provide any useful results.
swagger: "2.0"
info:
description: Initial draft of the API specification
version: '1.0'
title: App 4.0 API
host: api.com
basePath: /v1
tags:
- name: employees
description: Employee management
schemes:
- https
paths:
/employees/{employeeId}/roles:
get:
tags:
- employees
summary: "Get a specific employee's roles"
description: ''
operationId: findEmployeeRoles
produces:
- application/json
parameters:
- name: employeeId <====== Line 24
in: path
description: Id of employee whose roles we are fetching
type: integer
format: int64
responses:
'200':
description: successful operation
schema:
type: array
items:
$ref: '#/definitions/Role'
'403':
description: No permission to see employee roles
'404':
description: EmployeeId not found
Any Hints?
The error message is misleading. The actual error is that your path parameter is missing required: true. Path parameters are always required, so remember to add required: true to them.
Had the same problem. I accidentally mixed up the syntax from Swagger 2.0 with Openapi 3.0.x. In Openapi 3.0.x, definitions are redefined as components. In the online editor you can click on the button Edit > Convert to OpenAPI 3 to use Openapi 3.0.x.
Read more about components here.
Remark:
OAS 3 is the latest version of the
OpenAPI Specification.
For me the cause of the error was a missing a leading slash in the path (internal/resource instead of /internal/resource).
And yes the error message is extremely unhelpful.
In my case I was missing parameter definition in api definition
- name: parameterName
in: query
description: parameter's description here.
required: false
schema:
type: string
In my case it had the wrong indentation for the example. It was:
content:
application/json:
schema:
$ref: '#/components/schemas/someresponse'
examples:
example1:
value:
param1: "some string"
param2: "123"
Rather than:
content:
application/json:
schema:
$ref: '#/components/schemas/someresponse'
examples:
example1:
value:
param1: "some string"
param2: "123"
But the VScode open api preview with swaggerUI didn't show any errors and everything looked valid.
The syntax requires might require two parameters, as mentioned by Helen required: true is need so is type:DataType . The error is misleading.
I'm trying to write a simple Swagger / Open API definition using the Swagger Editor.
swagger: "2.0"
info:
version: 1.0.0
title: Test API
description: Test API
schemes:
- https
host: hipaa.ai
basePath: /v1
paths:
/comments:
post:
summary: Your comments
description: Comments
parameters:
- name: text
in: body
description: An array of text strings
type: array
minItems: 1
maxItems: 1000
items:
type: text
I'm getting the following error:
Schema error at paths./comments.post.parameters[0]
is not exactly one from <#/definitions/parameter>,<#/definitions/jsonReference>
I've checked the Swagger schema reference, and the petstore example, but I'm not sure why I'm getting this. Any ideas?
Body parameters use the schema keyword to specify the type, so you need to move type, items, minItems and maxItems under schema.
Also, type: text is not a valid type. Use type: string instead.
parameters:
- name: text
in: body
description: An array of text strings
schema:
type: array
minItems: 1
maxItems: 1000
items:
type: string