In YAML file I have this:
parameters:
- name: body
in: body
required: true
description: Body of the request.
schema:
$ref: '#/definitions/MinimalProgresstrailEntry'
and it's rendered to this:
:
it doesn't render the reference for the body. It works fine for the responses but not for parameters.
reference definitions:
MinimalProgresstrailEntry:
type: object
properties:
memoText:
type: string
type:
type: string
enum:
- memo
- attachment
- link
Following swagger file works on swagger-editor :
swagger: '2.0'
info:
version: "0.0.0"
title: title
paths:
/persons:
get:
description: test
parameters:
- name: body
in: body
required: true
description: Body of the request.
schema:
$ref: '#/definitions/MinimalProgresstrailEntry'
responses:
200:
description: Successful response
schema:
$ref: '#/definitions/MinimalProgresstrailEntry'
definitions:
MinimalProgresstrailEntry:
type: object
properties:
memoText:
type: string
type:
type: string
enum:
- memo
- attachment
- link
Related
I am trying to use Swagger. Below is the swagger.yml file.
swagger: "2.0"
basePath: /myapp/api
info:
description: My description
title: My title
version: 0.1.0
produces:
- application/json
consumes:
- application/json
schemes:
- http
paths:
/contract:
get:
operationId: "Get contract"
description: Get information
parameters:
- in: path
name: contractId
description: ID
required: true
schema:
type: integer
responses:
200:
description: Information...
schema:
$ref: "#/definitions/contract"
404:
description: "Not found."
post:
operationId: "Create"
parameters:
- in: body
name: contractId
schema:
$ref: '#/definitions/requestBodies/contract'
responses:
200:
description: Success...
400:
description: Problem...
definitions:
contract:
title: Contract
type: object
properties:
name:
title: Name
type: string
services:
title: Services
type: array
items:
title: Service
$ref: '#/definitions/service'
xyz:
title: Xyz
$ref: '#/definitions/virtualMachine'
service:
title: Service
type: object
properties:
containerName:
title: ContainerName
type: string
...
contracts:
title: Contracts
type: array
items:
title: Contract
$ref: '#/definitions/contract'
xyz:
title: Xyz
type: object
properties:
serverId:
title: ServerID
type: string
contractId:
title: ContractID
type: uuid
...
requestBodies:
contract:
content:
application/json:
schema:
$ref: '#/definitions/contract'
When I try to generate the documentation, I get the following error:
swagger generate server -f swagger.yml
2020/10/26 15:43:31 validating spec /home/dalton/workspace/.../.../swagger.yml
The swagger spec at "/home/dalton/workspace/.../.../swagger.yml" is invalid against swagger specification 2.0. see errors :
- definitions.requestBodies.contract in body is a forbidden property
- "definitions.xyz.properties.contractId.type" must validate at least one schema (anyOf)
- definitions.xyz.properties.contractId.type in body must be of type array: "string"
What am I doing wrong?
To make this code pass in the Swagger validation, I had to:
Remove the schema in the contractId parameter (get method);
Remove the requestBodies definition and change the schema in the contract parameter (post method);
Change the type of the contractId in the Xyz definition (the uuid type is not supported by the version 2 of Swagger).
The fixed code is below:
swagger: "2.0"
basePath: /myapp/api
info:
description: My description
title: My title
version: 0.1.0
produces:
- application/json
consumes:
- application/json
schemes:
- http
paths:
/contract:
get:
operationId: "Get contract"
description: Get information
parameters:
- in: path
name: contractId
description: ID
required: true
type: integer
responses:
200:
description: Information...
schema:
$ref: "#/definitions/contract"
404:
description: "Not found."
post:
operationId: "Create"
parameters:
- in: body
name: contractId
schema:
$ref: '#/definitions/contract'
responses:
200:
description: Success...
400:
description: Problem...
definitions:
contract:
title: Contract
type: object
properties:
name:
title: Name
type: string
services:
title: Services
type: array
items:
title: Service
$ref: '#/definitions/service'
xyz:
title: Xyz
$ref: '#/definitions/virtualMachine'
service:
title: Service
type: object
properties:
containerName:
title: ContainerName
type: string
...
contracts:
title: Contracts
type: array
items:
title: Contract
$ref: '#/definitions/contract'
xyz:
title: Xyz
type: object
properties:
serverId:
title: ServerID
type: string
contractId:
title: ContractID
type: string
format: uuid
Maybe you can try to edit your swagger.yml in the online Swagger Editor.
openapi: "3.0.0"
info:
title: project
servers:
- url: http://example1.net/v3
- url: http://example/v3
paths:
/Pn/{PnId}/service1:
post:
summary: Pn data
description: |
can Pn the data
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/dataInfo"
application/x-www-form-urlencoded:
schema:
$ref: "#/components/schemas/dataInfo"
parameters:
- name: PnId
in: path
description: PnId
required: true
schema:
$ref: "#/components/schemas/Pn"
responses:
'200':
description: status
content:
application/json:
schema:
$ref: "#/components/schemas/dataInfoStatus"
example: infoable
default:
description: error
content:
application/json:
schema:
$ref: "#/components/schemas/Error"
components:
schemas:
Error:
type: object
properties:
code:
type: integer
message:
type: string
required:
- message
Pn:
type: integer
format: int64
dataInfo:
type: string
dataInfoStatus:
type: string
enum: [infoable, non_infoable,ignorable]
I am sending a single dataInfo in request and getting single dataInfoStatus in response, but I will like to send and array of dataInfo and get an array of dataInfo status.
I tried following:
schema:
type:array
items:
$ref: "#/components/schemas/dataInfo"
but I get
Parser error bad indentation of a mapping entry
for items. I am following this.
How can I achieve sending dataInfo in request as an array of dataInfo and getting in response an array of dataInfoStatus?
You have to add one more space between type: and array, then the error message is gone:
schema:
type: array
items:
$ref: "#/components/schemas/dataInfo"
And you can add the info.version for the version of the openapi file.
Use path parameter petId as field value for id in request body. How can we do it?
openapi: "3.0.0"
info:
version: 1.0.0
title: Swagger Petstore
license:
name: MIT
servers:
- url: http://petstore.swagger.io/v1
paths:
/pets/{petId}:
put:
summary: Info for a specific pet
operationId: UpdatePetInfoById
tags:
- pets
parameters:
- name: petId
in: path
required: true
description: The id of the pet to retrieve
schema:
type: string
requestBody:
description: Info about a new pet
content:
application/json:
schema:
$ref: "#/components/schemas/Pet"
responses:
'200':
description: Expected response to a valid request
components:
schemas:
Pet:
required:
- id
- name
properties:
id: _{$request.path.petId}_
name:
type: string
tag:
type: string
In the following Swagger definition, I need the parameter labelValue to be of type LabelValueObject, so that it will be validated and correctly deserialized. However, I can't figure out the syntax! How can that be done?
swagger: "2.0"
paths:
/competition:
post:
parameters:
- name: labelValue
in: formData
type: array
items:
type: string ### this has to be a LabelValueObject ###
responses:
default:
description: Error
schema:
$ref: "#/definitions/AnyResponse"
definitions:
AnyResponse:
properties:
any:
type: string
LabelValueObject:
properties:
label:
type: string
value:
type: string
required:
- label
- value
The only way to pass an object as a parameter is to put it in the body (in: body) and then define this object in schema (inline definition or reference to an predefined object with $ref). Here's a full example:
swagger: "2.0"
info:
title: A dummy title
version: 1.0.0
paths:
/competition:
post:
parameters:
- name: labelValue
in: body
schema:
$ref: '#/definitions/LabelValueObject'
responses:
default:
description: Error
schema:
$ref: "#/definitions/AnyResponse"
definitions:
AnyResponse:
properties:
any:
type: string
LabelValueObject:
properties:
label:
type: string
value:
type: string
required:
- label
- value
Working on writing an API spec for my service with swagger. I'm using a model definition ('#/definitions/prototype') as the body parameter of both the POST /prototypes and PATCH /prototypes/:id routes.
How do you specify that the PATCH route only accepts a subset of the properties in the body of the request that the POST route does? For example, I want the PATCH /instances/:id route to only allow modification of the mobileDeviceId prototypes property.
swagger: "2.0"
info:
title: ""
description: ""
version: "1.0.0"
host: foo.example.com
schemes:
- https
basePath: /v1
produces:
- application/json
consumes:
- application/json
paths:
/prototypes:
post:
summary: Create new prototype
parameters:
- name: prototype
in: body
description: Prototype object
required: true
schema:
$ref: "#/definitions/Prototype"
responses:
201:
description: Success
schema:
$ref: "#/definitions/SuccessCreated"
403:
description: Prototype limit exceeded error
schema:
$ref: "#/definitions/Error"
default:
description: Unexpected error
schema:
$ref: "#/definitions/Error"
/prototypes/{id}:
patch:
summary: Update an existing prototype's properties
parameters:
- name: id
in: path
type: number
description: ID property of a prototype
required: true
- name: prototype
in: body
description: Prototype object
required: true
schema:
$ref: "#/definitions/Prototype"
responses:
200:
description: Success
definitions:
Prototype:
type: object
properties:
id:
type: integer
format: int64
name:
type: string
mobileDeviceId:
type: number
SuccessCreated:
type: object
description: Returned as response to successful resource create request
properties:
code:
type: number
default: 201
message:
type: string
Error:
type: object
properties:
code:
type: integer
format: int32
message:
type: string
fields:
type: string
Swagger uses json-schema: http://json-schema.org
$refs provide you w/ a way to repeat existing json-schema at a new path.
Notice that you are using a $ref for patch/parameters/-name:prototype/schema.
You can create a new definition just for patch in the definitions section and reference it instead
swagger: "2.0"
info:
title: ""
description: ""
version: "1.0.0"
host: foo.example.com
schemes:
- https
basePath: /v1
produces:
- application/json
consumes:
- application/json
paths:
/prototypes:
post:
summary: Create new prototype
parameters:
- name: prototype
in: body
description: Prototype object
required: true
schema:
$ref: "#/definitions/Prototype"
responses:
201:
description: Success
schema:
$ref: "#/definitions/SuccessCreated"
403:
description: Prototype limit exceeded error
schema:
$ref: "#/definitions/Error"
default:
description: Unexpected error
schema:
$ref: "#/definitions/Error"
/prototypes/{id}:
patch:
summary: Update an existing prototype's properties
parameters:
- name: id
in: path
type: number
description: ID property of a prototype
required: true
- name: prototype
in: body
description: Prototype object
required: true
schema:
$ref: "#/definitions/PatchPrototype"
responses:
200:
description: Success
definitions:
Prototype:
type: object
properties:
id:
type: integer
format: int64
name:
type: string
mobileDeviceId:
type: number
PatchPrototype:
type: object
properties:
mobileDeviceId:
type: number
SuccessCreated:
type: object
description: Returned as response to successful resource create request
properties:
code:
type: number
default: 201
message:
type: string
Error:
type: object
properties:
code:
type: integer
format: int32
message:
type: string
fields:
type: string