I am using swagger with Open API 3.0.0
Following is my Api definition:
paths:
/offerers:
get:
summary: give all offerers back
operationId: allOfferers
description: give you all offerers back
responses:
'200':
description: oferers results
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/OfferersId'
links:
GetSingleOffererById:
$ref: '#/components/links/GetSingleOffererById'
'400':
description: something went terribly wrong
/offerers/{offererId}:
parameters:
- in: path
name: offererId
schema:
$ref: '#/components/schemas/OfferersId'
required: true
get:
parameters:
- $ref: '#/components/schemas/OfferersId'
summary: give one specified offerer back
operationId: singleOfferer
description: give one offerer back. Specified by its id
responses:
'200':
description: offerers results
content:
application/json:
schema:
$ref: '#/components/schemas/Offerers'
'400':
description: something went terribly wrong
components:
schemas:
OfferersId:
type: number
example: 123
Offerers:
type: object
required:
- offererId
- name
properties:
id:
$ref: '#/components/schemas/OfferersId'
name:
type: string
example: "Mark Mustermann"
location:
type: string
example: "90449 Nürnberg"
experience:
type: string
example: "8 Jahre"
openingHours:
type: string
example: "Werktags: 10:15-18:30/tWochenende: geschlossen."
links:
GetSingleOffererById:
operationId: singleOfferer
description: the offererId in the response will be used as offererId in the request
paramters:
offererId: $reponse.body#/OfferersId
Most of this Definition is error free. But the last section components/links gives me an error at line "operationId: singleOfferer":
should NOT have additional properties additionalProperty: operationId,
paramters
So my question:
How do I have to correct my definition, so that the reusable link is valid?
"should NOT have additional properties" error in the Swagger Editor usually means one of the following:
a keyword is misspelt,
syntax/structure is incorrect.
In your example it's (1) - paraMTers should be paraMETers.
Related
I'm trying to create an enum as a reusable object in my swagger and swagger is erroring with:
Structural error at components.schemas.Project.properties.location
should NOT have additional properties
additionalProperty: schema
Jump to line 47
I have the enum specified in the components/schemas section and I am then referencing it using $ref: '#/components/schemas/Registry'. I was trying to follow the example here: https://swagger.io/docs/specification/data-models/enums/
This is the full swagger file:
openapi: 3.0.3
info:
title: My API
description: |-
Blah
contact:
email: support#example.com
version: 1.0.0
externalDocs:
description: Find out more about blah
url: http://blah.io
paths:
/credits-received:
post:
tags:
- Credits Received
operationId: creditsReceived
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CreditsReceivedData'
required: true
responses:
'200':
description: Successful operation
components:
schemas:
CreditsReceivedData:
required:
- project
type: object
properties:
project:
$ref: '#/components/schemas/Project'
Project:
required:
- name
- registry
type: object
properties:
name:
type: string
example: "Project 1"
registry:
type: string
example: "My Registry"
schema:
$ref: '#/components/schemas/Registry'
Registry:
type: string
enum:
- My Registry 1
- My registry 2
I solved this by replacing
registry:
type: string
example: "My Registry"
schema:
$ref: '#/components/schemas/Registry'
with
registry:
$ref: '#/components/schemas/Registry'
Basically remove the schema attribute, just put the $ref directly under the property (registry in this case).
I am trying to generate the API documentation using swagger editor. I specified my API specification as follow
paths:
/opendata/v1/{index}:
get:
tags: [verification]
description: Verify the person information
parameters:
- name: index
in: path
description: specific data index
required: true
type: string
- name: name
in: query
description: name of a person
required: false
type: string
- name: company name
in: query
description: name of a company
required: false
type: string
responses:
'200':
description: Success
content:
application/json:
schemas:
$ref: '#/responses/200'
responses:
'200':
description: Success
schema:
type: object
properties:
verification:
type: string
But its always showing error in the editor that "Not a valid response definition". I checked the specification for response from here. What changes I should do so that error will not come.
Note: I want the response in the json form like below:
{
verification:string
}
You are mixing OpenAPI/Swagger 2.0 and OpenAPI 3.0 syntax. Your spec seems to be swagger: '2.0', so you should use:
paths:
/opendata/v1/{index}:
get:
...
produces:
- application/json
responses:
200:
$ref: '#/responses/200'
Here's a related OpenAPI/Swagger 2.0 guide: Describing Responses
I'm trying to figure out this swagger API inheritance stuff by using allOf. This is my swagger yaml file.
swagger: '2.0'
info:
title: Test API
version: '1'
basePath: /api/v1
schemes:
- https
produces:
- application/json
paths:
/users:
get:
summary: Collection of users
tags:
- users
responses:
200:
description: A list of Users
schema:
$ref: "#/definitions/Users"
500:
$ref: "#/responses/BadRequest"
definitions:
User:
required:
- username
properties:
firstName:
type: string
lastName:
type: string
username:
type: string
Users:
type: array
items:
$ref: "#/definitions/User"
responses:
NonSuccess:
description: Generic response for all non-success responses
schema:
type: object
required:
- code
- message
properties:
code:
type: integer
description: The success code, 0 or -1.
message:
type: string
description: The description message for this success code
errors:
type: array
description: A map of errors within the request. Keyed by the parameter name and the values are the error details
BadRequest:
description: Invalid request parameters
allOf:
- $ref: "#/responses/NonSuccess"
When I paste this into the online editor, I get the following errors that I'm having a real hard time trying to figure out.
✖ Swagger Error
Additional properties not allowed: allOf
Jump to line 60
✖ Swagger Error
Not a valid response definition
Jump to line 22
The main problem seems to be Additional properties not allowed: allOf and I'm can't seem to figure out what I'm doing wrong in this case. I was trying to declare a basic non-success response so that all non-200 responses will inherit so that the API will have a very standard looking non-success response. I was under the impression I could do this with allOf and then add or overwrite the fields from that response. What exactly am I doing wrong?
The allOf tag can only be used on Schema objects. You can definitely use it on the Schema portion of the response, though. Here's an example of that.
swagger: '2.0'
info:
title: Test API
version: '1'
basePath: /api/v1
schemes:
- https
produces:
- application/json
paths:
/users:
get:
summary: Collection of users
tags:
- users
responses:
200:
description: A list of Users
schema:
$ref: "#/definitions/Users"
500:
$ref: "#/responses/BadRequest"
definitions:
User:
required:
- username
properties:
firstName:
type: string
lastName:
type: string
username:
type: string
Users:
type: array
items:
$ref: "#/definitions/User"
Response:
type: object
required:
- code
- message
properties:
code:
type: integer
description: The success code, 0 or -1.
message:
type: string
description: The description message for this success code
errors:
type: array
description: A map of errors within the request. Keyed by the parameter name and the values are the error details
BadRequest:
type: object
required:
- validationErrors
properties:
validationErrors:
type: array
items:
type: string
responses:
NonSuccess:
description: Generic response for a non-success
schema:
$ref: "#/definitions/Response"
BadRequest:
description: Invalid request parameters
schema:
allOf:
- $ref: "#/definitions/Response"
- $ref: "#/definitions/BadRequest"
I have a few endpoints where I have some standard error responses like 404, 401, 403 and default. I want to refactor these responses to a Swagger definition but I am not able to achieve this. I tried a few tricks but it always resulted in parsing errors. Here is the yaml I have.
swagger: '2.0'
info:
title: My API
description: My API description
version: 0.0.1
host: api.example.com
schemes:
- https
basePath: /
produces:
- application/json
paths:
/users:
get:
operationId: getUsers
summary: Get users
description: Get all users
tags:
- Users
responses:
'200':
description: An array of users
schema:
type: array
items:
$ref: '#/definitions/User'
'401':
description: Authentication required
schema:
$ref: '#/definitions/Error'
'402':
description: Payment required
schema:
$ref: '#/definitions/Error'
'403':
description: Unauthorized access
schema:
$ref: '#/definitions/Error'
'404':
description: Not found
schema:
$ref: '#/definitions/Error'
default:
description: Unexpected error
schema:
$ref: '#/definitions/Error'
/games:
get:
operationId: getGames
summary: Get games
description: Get all games
tags:
- Games
responses:
'200':
description: An array of games
schema:
type: array
items:
$ref: '#/definitions/Game'
'401':
description: Authentication required
schema:
$ref: '#/definitions/Error'
'402':
description: Payment required
schema:
$ref: '#/definitions/Error'
'403':
description: Unauthorized access
schema:
$ref: '#/definitions/Error'
'404':
description: Not found
schema:
$ref: '#/definitions/Error'
default:
description: Unexpected error
schema:
$ref: '#/definitions/Error'
definitions:
User:
type: object
properties:
id:
type: integer
description: Unique id of user
name:
type: string
description: Name of user
Game:
type: object
properties:
id:
type: integer
description: Unique id of game
name:
type: string
description: Name of game
Error:
type: object
properties:
code:
type: integer
description: HTTP status code
message:
type: string
description: Message describing error
Observe the repeating responses in /users and /games. How do I refactor and move them to definitions?
You can use shared responses object to define the responses. Then refer them in the individual operations. From the spec about shared responses object:
An object to hold responses to be reused across operations. Response
definitions can be referenced to the ones defined here.
While this would be a valid spec, Swagger-UI won't be able to parse from the shared responses except default response. Here is the issue related to this.
I Have this YAML code of swagger and I need to create my own type (named MyOwnType).
If I use "MyOwnType" a compilation error occurs.
paths:
/in/total:
get:
summary: My summary.
description: My description.
parameters:
- name: total
in: query
description: Total.
required: true
type: MyOwnType # -- THIS LINE OCCURS ERROR --
format: MyOwnType
responses:
201:
description: Respose
schema:
$ref: '#/definitions/MyOwnType'
definitions:
MyOwnType:
properties:
var:
type: string
description: data.
I created a definition "MyOwnType" and I can use like that: "$ref: '#/definitions/MyOwnType'" in schema.
But how can I use the "MyOwnType" definition on a parameter type?
A query parameter can not have a JSON Schema. If you want to have schema for your parameter you should change in of your parameter to body or formData and use schema key:
swagger: '2.0'
info:
version: 0.0.0
title: '<enter your title>'
paths:
/in/total:
get:
summary: My summary.
description: My description.
parameters:
- name: total
in: body
description: Total.
required: true
schema:
$ref: '#/definitions/MyOwnType'
responses:
201:
description: Respose
schema:
$ref: '#/definitions/MyOwnType'
definitions:
MyOwnType:
properties:
var:
type: string
description: data.