is it possible to have an array of complex object inside the get parameters?
If I try this code, I get a parameter definition error due to this line: $refs: '#/definitions/pax'
swagger: '2.0'
info:
version: 0.0.0
title: Simple API
paths:
/:
get:
parameters:
- name: passengers
in: query
type: array
items:
$refs: '#/definitions/pax'
responses:
200:
description: TODO
definitions:
pax:
type: object
properties:
name:
type: string
familyname:
type: string
For request parameters, only body parameter can be defined with an Object (model).
You will need to provide an example of the URL query string so that we can help you define it with Swagger/OpenAPI spec.
Related
I am trying to create OpenAPI definition for a Webcase Create meeting. This is my YAML code:
openapi: '3.0.0'
info:
title: WebcastCreateMeeting
version: "1.1"
servers:
- url: https://api.webcasts.com/api
paths:
'/event/create':
post:
tags:
- CreateMeetingCallbody
summary: EventGM
parameters:
- in: path
name: event_title # >> line 15
description: name of the event from Cvent
required: true
schema:
type: string
responses:
200:
description: This would be the response.
content:
application/json;charset=utf-8:
schema:
type: array
items:
properties:
scheduled_duration:
type: integer
example: 30
event_id:
type: integer
example: 0000000
event_title:
type: string
example: Cvent Testing sync event
The error I see in the Swagger Editor is:
Semantic error at paths./event/create.post.parameters.0.name
Path parameter "event_title" must have the corresponding {event_title} segment in the "/event/create" path
Jump to line 15
What does this error mean and how to fix it?
When using path parameters (in: path), the path must include the parameter name in curly braces { }, to indicate where exactly in the path that parameter is inserted.
paths:
'/event/create/{event_title}':
See Describing Path Parameters for details.
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 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
Can not get how to use reference of string type with enum values in array parameter.
I can make reference in items key and it is working, but Swagger produce error: Not a valid parameter definition
Web UI generates interface, but it have textarea instead of multiselect box I expected.
What is the proper way to do it?
My code:
swagger: '2.0':
paths:
/test:
get:
parameters:
- in: origin
name: status
description: Origin
required: false
schema:
type: array
items:
$ref: '#/definitions/Origin'
collectionFormat: pipes'
definitions:
Origin:
type: string
description: Campaign origin
enum:
- one
- two
externalDocs:
description: Find out more about Swagger
url: http://swagger.io
host: virtserver.swaggerhub.com
basePath: /
Array parameters with items containing $ref are not supported in OpenAPI/Swagger 2.0. But it looks like this will be possible in the next version, 3.0. For now there are a couple of workarounds, see below.
Your spec also has some other issues:
in: origin is not valid. The in keyword specifies the parameter location (path, query, header, etc.) and only accepts certain values as per the OpenAPI/Swagger spec. I guess you meant in: query or in: header.
Typos (or copy-paste errors?): swagger: '2.0': has an extra : at the end and collectionFormat: pipes' has an extra ' at the end.
One solution for having an array parameter containing enum values is to define the enum inline:
parameters:
- in: query
name: status
description: Origin
required: false
type: array
collectionFormat: pipes
items:
type: string
enum:
- one
- two
Another solution (found here) is to use YAML anchors to reference the enum. This is a feature of YAML where you can mark a key with &anchor-name and then further down use *anchor-name to reference that key's value.
definitions:
Origin:
type: string
description: Campaign origin
enum: &origin
- one
- two
paths:
/test:
get:
parameters:
- in: query
name: status
description: Origin
required: false
type: array
collectionFormat: pipes
items:
type: string
enum: *origin
One option is to define a parameter and make a reference to that: (I had an issue with using reference ($ref:) within a query definition)
paths:
/path:
get:
operationId: controllers.controller
parameters:
**- $ref: '#/parameters/SPEC'**
parameters:
SPEC:
Is it possible to group multiple parameters to reference them in multiple routes?
For example I have a combination of parameters which I need in every route. They are defined as global parameters. How can I group them?
I think about a definition like this:
parameters:
MetaDataParameters:
# Meta Data Properties
- name: id
in: query
description: Entry identification number
required: false
type: integer
- name: time_start
in: query
description: Start time of flare
required: false
type: string
- name: nar
in: query
description: Active region number
required: false
type: string
And then reference the whole group in my route:
/test/:
get:
tags:
- TEST
operationId: routes.test
parameters:
- $ref: "#/parameters/MetaDataParameters"
responses:
200:
description: OK
Is this possible with Swagger 2.0?
This is not possible with Swagger 2.0, OpenAPI 3.0 or 3.1. I've opened a feature request for this and it is proposed for a future version:
https://github.com/OAI/OpenAPI-Specification/issues/445
you can point your $ref to middle .yaml file, like this:
//middle.yaml <-----
- $ref: 'Defaul.yaml#/components/parameters/meta_id'
- $ref: 'Defaul.yaml#/components/parameters/meta_time_start'
- $ref: 'Default.yaml#/components/parameters/meta_nar'
your Default.yaml file should be like this:
//Default.yaml <-----
components:
parameters:
meta_id:
name: id
in: query
description: Entry identification number
schema:
type: integer
example: 1
meta_time_start:
name: time_start
in: query
schema:
type: string
finally, your main file should be looks like this:
/test/:
get:
tags:
- TEST
operationId: routes.test
parameters:
$ref: "../parameters/middle.yaml" <---- external yaml file
responses:
200:
description: OK
NOTE: your $ref should be without -. like in my example