---
swagger: '2.0'
info:
version: 0.0.0
title: Simple API
paths:
/:
get:
responses:
200:
description: OK
definitions:
Thing:
properties:
parent_thing:
allOf:
- $ref: '#/definitions/Thing'
description: parent of this thing
Here is the minimal example. If I write this in swagger-editor, it shows that parent_thing is of type undefined: https://i.imgur.com/OGHlKxg.png
How do I fix that? I want Thing to have a reference to other Things.
You can have self-references, but you probably don't use the allOf construct:
definitions:
Thing:
properties:
parent_thing:
$ref: '#/definitions/Thing'
The above is valid, if the swagger-editor is not showing it correctly, that is a bug.
You can achieve that by a proxy model (https://stackoverflow.com/a/59047433/1046909):
...
_MessageProxy:
description: Message
type: object
required:
- id
- user
- body
- publishedAt
properties:
id:
title: Message id
type: string
readOnly: true
example: '595f4acf828b0b766ad11290'
user:
$ref: '#/components/schemas/User'
Message:
allOf:
- $ref: '#/components/schemas/_MessageProxy'
- type: object
properties:
parent:
title: Parent
readOnly: true
allOf:
- $ref: '#/components/schemas/_MessageProxy'
...
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 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.
here is the code.When I write allOF instead oneOF then everything is ok,but with oneOf it doesn't show anything and there is no error.Did I write something wrong or it is still not working in swagger 3.0.0.Also any of is not woking.Or do we have something like oneOf but in swagger 2.0
openapi: 3.0.0
servers:
- url: 'http://petstore.swagger.io/v2'
x-origin:
- url: 'http://petstore.swagger.io/v2/swagger.json'
format: swagger
version: '2.0'
converter:
url: 'https://github.com/mermade/swagger2openapi'
version: 2.2.0
info:
description: 'This is a sample.'
version: 1.0.0
title: Swagger Petstore
termsOfService: 'http://swagger.io/terms/'
contact:
email: apiteam#swagger.io
license:
name: Apache 2.0
url: 'http://www.apache.org/licenses/LICENSE-2.0.html'
tags:
- name: pet
description: Everything about your Pets
externalDocs:
description: Find out more
url: 'http://swagger.io'
- name: store
description: Access to Petstore orders
- name: user
description: Operations about user
externalDocs:
description: Find out more about our store
url: 'http://swagger.io'
paths:
/something:
post:
requestBody:
required: true
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/Dog'
- $ref: '#/components/schemas/Cat'
responses:
'200':
description: Updated
components:
schemas:
Dog:
type: object
properties:
bark:
type: boolean
breed:
type: string
enum: [Dingo, Husky, Retriever, Shepherd]
Cat:
type: object
properties:
hunts:
type: boolean
age:
type: integer
swagger-ui-express 4.1.12 not supporting oneof,anyof version
openapi: 3.0.1
tags:
- name: API Specification
description: All endpoints and payloads about Project
paths:
/pets:
patch:
requestBody:
content:
application/json:
schema:
- $ref: '#/components/schemas/Cat'
- $ref: '#/components/schemas/Dog'
responses:
'200':
description: Updated
components:
schemas:
Dog:
type: object
properties:
bark:
type: boolean
breed:
type: string
enum: [Dingo, Husky, Retriever, Shepherd]
Cat:
type: object
properties:
hunts:
type: boolean
age:
type: integer
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.