I have the swagger API description (yaml / v 3.0) as stated below. I get the error
Structural error at paths./AanwezigLeden/Aanmelden.post.requestBody.content.application/json.schema
should NOT have additional properties
additionalProperty: allOff
What I want is an API description of a post method with an object as specified oper_aanwezig_leden, with one additional field as body.
/AanwezigLeden/Aanmelden:
post:
summary: Aanmelden van het lid als aanwezig.
requestBody:
description: Lid data
required: true
content:
application/json:
schema:
allOff:
- ref: '#/components/schemas/oper_aanwezig_leden'
- type: string
name: TIJDSTIP
description: Tijdstip van de aanmelding. Indien afwezig, huidige tijd. ISO8601
required: false
responses:
200:
description: "OK, data succesvol aangepast"
content:
application/json:
schema:
$ref: '#/components/schemas/oper_aanwezig_leden'
401:
description: "Niet geautoriseerd, geen schrijfrechten"
404:
description: "Data niet gevonden"
405:
description: "Methode niet toegestaan, input validatie error"
406:
description: "Niet aanvaardbaar, input ontbreekt"
500:
description: "Data verwerkingsfout, bijv onjuiste veldwaarde (string ipv integer)"
This triggered me for solving the issue. However, there is more than a typo
/AanwezigLeden/Aanmelden:
post:
summary: Aanmelden van het lid als aanwezig.
requestBody:
description: Lid data
required: true
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/oper_aanwezig_leden_in'
- type: object
properties:
TIJDSTIP:
description: Tijdstip van de aanmelding. Indien afwezig, huidige tijd. ISO8601
type: string
format: date-time
example: "2017-07-21T09:32:28Z"
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
With OpenAPI Is there a way to include examples by reference with the $ref: tag that doesn't not require adding the "value" key?
See examples I've added to the petstore.yaml:
openapi: "3.0.0"
info:
version: 1.0.0
title: Swagger Petstore
license:
name: MIT
servers:
- url: http://petstore.swagger.io/v1
paths:
/pets:
get:
summary: List all pets
operationId: listPets
tags:
- pets
parameters:
- name: limit
in: query
description: How many items to return at one time (max 100)
required: false
schema:
type: integer
format: int32
responses:
'200':
description: A paged array of pets
headers:
x-next:
description: A link to the next page of responses
schema:
type: string
content:
application/json:
schema:
$ref: "#/components/schemas/Pets"
example:
$ref: "#/components/examples/animals"
default:
description: unexpected error
content:
application/json:
schema:
$ref: "#/components/schemas/Error"
post:
summary: Create a pet
operationId: createPets
tags:
- pets
responses:
'201':
description: Null response
default:
description: unexpected error
content:
application/json:
schema:
$ref: "#/components/schemas/Error"
/pets/{petId}:
get:
summary: Info for a specific pet
operationId: showPetById
tags:
- pets
parameters:
- name: petId
in: path
required: true
description: The id of the pet to retrieve
schema:
type: string
responses:
'200':
description: Expected response to a valid request
content:
application/json:
schema:
$ref: "#/components/schemas/Pet"
example:
$ref: "#/components/examples/garfield"
default:
description: unexpected error
content:
application/json:
schema:
$ref: "#/components/schemas/Error"
components:
schemas:
Pet:
type: object
required:
- id
- name
properties:
id:
type: integer
format: int64
name:
type: string
tag:
type: string
Pets:
type: array
items:
$ref: "#/components/schemas/Pet"
Error:
type: object
required:
- code
- message
properties:
code:
type: integer
format: int32
message:
type: string
examples:
garfield:
id: 1
name: garfield
tag: cat
grumpycat:
id: 2
name: grumpycat
tag: cat
odie:
id: 3
name: odie
tag: dog
animals:
- $ref: "#/components/examples/garfield"
- $ref: "#/components/examples/grumpycat"
- $ref: "#/components/examples/odie"
openapi-generator-cli validate says it's invalid OpenAPI as does my OpenAPI plugin for VSCode. Error log output:
Validating spec (/local/petstore.yaml)
Errors:
-attribute components.examples.odie.name is unexpected
-attribute components.examples.garfield.id is unexpected
-attribute components.examples.grumpycat.name is unexpected
-attribute components.examples.animals is not of type `object`
-attribute components.examples.garfield.tag is unexpected
-attribute components.examples.garfield.name is unexpected
-attribute components.examples.odie.tag is unexpected
-attribute components.examples.grumpycat.id is unexpected
-attribute components.examples.grumpycat.tag is unexpected
-attribute components.examples.odie.id is unexpected
[error] Spec has 10 errors.
I can correct the errors by adding a value key like this:
examples:
garfield:
value:
id: 1
name: garfield
tag: cat
grumpycat:
value:
id: 2
name: grumpycat
tag: cat
odie:
value:
id: 3
name: odie
tag: dog
animals:
value:
- $ref: "#/components/examples/garfield"
- $ref: "#/components/examples/grumpycat"
- $ref: "#/components/examples/odie"
The problem with this is that, my examples now include the value property, which I don't want as it's not part of the schema:
{
"value": {
"id": 1,
"name": "garfield",
"tag": "cat"
}
}
Question: Is there a way for me to define the examples by $ref as I have done WITHOUT using introducing the "value" property?
The correct syntax is as follows:
components:
examples:
garfield:
value:
id: 1
name: garfield
tag: cat
grumpycat:
value:
id: 2
name: grumpycat
tag: cat
odie:
value:
id: 3
name: odie
tag: dog
animals:
summary: An array of two animals
value:
- id: 1
name: garfield
tag: cat
- id: 2
name: grumpycat
tag: cat
paths:
/pets:
get:
...
responses:
'200':
description: A paged array of pets
...
content:
application/json:
schema:
$ref: "#/components/schemas/Pets"
examples:
animals:
$ref: "#/components/examples/animals"
/pets/{petId}:
get:
...
responses:
'200':
description: Expected response to a valid request
content:
application/json:
schema:
$ref: "#/components/schemas/Pet"
examples:
garfield:
$ref: "#/components/examples/garfield"
grumpycat:
$ref: '#/components/examples/grumpycat'
odie:
$ref: '#/components/examples/odie'
Explanation:
Examples in the components/examples section must use the Example Object syntax. That is, the actual example value must be wrapped into the value key.
To reference examples from the components/examples section, you must use the examples keyword (plural; not singular example). examples is supported in parameters and in media types, but not in schemas.
Within the literal example value, $ref is not supported. That is, you cannot $ref a part of an example.
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