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:
schema
in the contractId
parameter (get method);schema
in the contract
parameter (post method);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