Menu
Using Swagger 2.0 I am trying to specify an input parameter of type object:
code snippet:
paths:
'/thingies/{thingy_id}.json':
put:
summary: Update an existing thingy
description: Updates an existing thingy
parameters:
- name: thingy_id
description: ID of the thingy to update
in: path
required: true
type: integer
- name: translation
description: Name and Locale for new translation
in: formData
type: object
properties:
name:
type: string
locale:
type: string
However the validator is complaining about the type: object part.
How ought I correctly specify my input parameters?
522
You can use the default key to specify the default value for an optional parameter. The default value is the one that the server uses if the client does not supply the parameter value in the request. The value type must be the same as the parameter's data type.
If you are trying to send a body with multiple parameters, add an object model in the definitions section and refer it in your body parameter, see below (works with editor.swagger.io):
Describing Parameters In Swagger, API operation parameters are defined under the parameters section in the operation definition. Each parameter has name, value type (for primitive value parameters) or schema (for request body), and optional description. Here is an example:
Swagger allows for object inputs only as body parameters. The reason for that relates to the way content is serialized which depends on the Content-Type header ( produces in Swagger). That header relates to the payload as a whole.
In the Swagger specification, the data types are used in several locations - Operations, Operation Parameters, Models, and within the data types themselves (arrays). The fields used to describe a given data type are added flatly to the relevant object.
OpenAPI 3.0 describes how this is possible here: In the meantime you could just have the query parameter as a plain old string type and then perform the serialization manually, then set the query parameter as required. This is what I'm doing until Swagger UI fully supports OpenAPI 3.0.
Okay, thanks to the input from @ron I have worked out the solution. Yes I need to use body instead of formData but even then it didn't validate, complaining about type: object. But if I define the object first then $ref it then it all works. The following code does validate.
swagger: '2.0'
info:
version: '1'
title: Thingy Service
description: Everyone loves their thingy
schemes:
- http
consumes:
- application/json
produces:
- application/json
definitions:
localisation:
type: object
required:
- name
- locale
properties:
name:
type: string
locale:
type: string
paths:
'/thingies/{thingy_id}.json':
put:
summary: Update an existing thingy
description: Updates an existing thingy
parameters:
- name: thingy_id
description: ID of the thingy to update
in: path
required: true
type: integer
- name: translation
description: Name and Locale for new translation
in: body
schema:
$ref: '#/definitions/localisation'
responses:
204:
description: No data
404:
description: Thingy not found
If you love us? You can donate to us via Paypal or buy me a coffee so we can maintain and grow! Thank you!
Donate Us With