I am new to Swagger, and I have being fixing some errors I got after importing the .json file into https://editor.swagger.io/ but I am getting this error.
Declared path parameter "PARAMETER" needs to be defined within every
operation in the path (missing in "get"), or moved to the path-level
parameters object
Here is the part that is giving me the error:
'/api/v1/images/{PARAMETER}/{type}':
get:
tags:
- Images
summary: 'summar'
operationId: DownloadFIle
consumes: []
produces:
- application/json
parameters:
- name: PARAMETER
in: path
required: true
type: string
- name: type
in: path
required: true
type: string
responses:
'200':
description: Success
schema:
uniqueItems: false
type: array
items:
$ref: '#/definitions/CloudImageInfo'
'400':
description: Bad Request
schema:
$ref: '#/definitions/ErrorResponse'
'401':
description: Unauthorized
schema:
type: string
'404':
description: Not Found
schema:
type: string
'500':
description: Server Error
schema:
$ref: '#/definitions/ErrorResponse'
post:
tags:
- Images
summary: summary
description: " description"
operationId: UploadFile
consumes:
- multipart/form-data
produces:
- application/json
parameters:
- name: imageFiles
in: formData
required: false
type: array
items: {}
collectionFormat: multi
uniqueItems: false
- name: PARAMETER
in: path
required: true
type: string
- name: type
in: path
required: true
type: string
responses:
'201':
description: Success
schema:
uniqueItems: false
type: array
items:
$ref: '#/definitions/CloudImageInfo'
'400':
description: Bad Request
schema:
$ref: '#/definitions/ErrorResponse'
'401':
description: Unauthorized
schema:
type: string
'500':
description: Server Error
schema:
$ref: '#/definitions/ErrorResponse'
can anyone point me where to look or what can I fix?
Related
I'm trying to use OpenAPI v3 to define models with polymorphism. I've tried the following model definitions and, while they appear to be successfully processed by the Redocly linter, the API documentation generated by Redocly seems to fail to properly document the models.
Here are the OpenAPI document:
openapi: 3.0.3
info:
version: 0.0.3-SNAPSHOT
title: Pet Adaption API
description: |
Adopt a pet!
servers:
- url: 'https://example/pet/api/v1'
description: Pet Adaption API
paths:
/pet_adaptions:
post:
summary: Mark a pet for adaption
description: Mark a pet for adaption
operationId: adopt
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/PetType'
required: true
responses:
200:
description: The pet was marked for adaption
400:
description: The payload was poorly formatted.
500:
description: Unexpected server error.
components:
schemas:
Pet:
type: object
required:
- name
properties:
name:
type: string
description: What goes on their collar.
PetType:
type: object
oneOf:
- $ref: '#/components/schemas/Cat'
- $ref: '#/components/schemas/Dog'
discriminator:
propertyName: type
mapping:
CAT: '#/components/schemas/Cat'
DOG: '#/components/schemas/Dog'
Dog:
type: object
oneOf:
- $ref: '#/components/schemas/LargeDog'
- $ref: '#/components/schemas/SmallDog'
discriminator:
propertyName: size
mapping:
large: '#/components/schemas/LargeDog'
small: '#/components/schemas/SmallDog'
required:
- type
properties:
type:
type: string
description: The type of pet. Always set to `DOG`
LargeDog:
type: object
allOf:
- $ref: '#/components/schemas/Pet'
required:
- size
- floofFactor
properties:
size:
type: string
description: The size of dog. Always set to `large`
floofFactor:
type: integer
description: Floofiness of large dog (1 - 10)
SmallDog:
type: object
allOf:
- $ref: '#/components/schemas/Pet'
required:
- type
- size
- yapFactor
properties:
type:
type: string
description: The type of pet. Always set to `DOG`
size:
type: string
description: The size of dog. Always set to `small`
yapFactor:
type: number
description: Yapiness of small dog (0 - 1.0)
Cat:
type: object
allOf:
- $ref: '#/components/schemas/Pet'
required:
- type
- colour
properties:
type:
type: string
description: The type of pet. Always set to `CAT`
colour:
type: string
description: Colour if the cat's coat
And the following should all be valid examples:
LargeDog
{
"name": "Rex",
"type": "DOG",
"size": "large",
"floofFactor": 3
}
SmallDog
{
"name": "Skip",
"type": "DOG",
"size": "small",
"yapFactor": 0.9
}
Cat
{
"name": "Mr Tinkles",
"type": "CAT",
"colour": "black"
}
The API documentation renders just fine if looking at the CAT example but not when looking at the DOG example.
Have I created an invalid OpenAPI v3 document or is this likely just an issue with Redocly?
Try to pass the discriminator inside size property.
Dog:
type: object
required:
- type
properties:
type:
type: string
description: The type of pet. Always set to `DOG`
size:
type: string
description: The type of pet. Always set to `DOG`
discriminator:
propertyName: size
mapping:
large: '#/components/schemas/LargeDog'
small: '#/components/schemas/SmallDog'
oneOf:
- $ref: '#/components/schemas/LargeDog'
- $ref: '#/components/schemas/SmallDog'
enter image description here
I am trying to create a swagger doc for a post meetings call. I am unsure how to add body fields under parameters (like meeting.name, meeting.time, meeting.duration etc). I get the error in the parameters "allowedValues: path, query, header, cookie". I am unsure which one to pick from here? I am done this previously by writing "-in: body" but body doesn't seem to be an option here.
openapi: '3.0.0'
info:
title: WebcastCreateMeeting
version: "1.1"
servers:
- url: https://api.webcasts.com/api
paths:
'/event/create/{event_title}/{folder_id}/{type}/{scheduled_start_time}/{scheduled_duration}/{timezone}/{region}/{acquisition_type}/{audience_capacity}/{event_expiration_months}/{token}':
post:
tags:
- CreateMeetingCallbody
summary: EventGM
parameters:
- in: path
name: token
description: the auth token
required: true
schema:
type: string
example: 123j1lkj3lk1j3i1j23l1kj3k1j2l3j12l3j1l2
- in: path
name: event_title
description: Name of the event from Cvent
required: true
schema:
type: string
- in: body
name: user
description: this is a test user
schema:
type: object
required:
- username
properties:
username:
type: string
- in: path
name: folder_id
description: ID of the folder under whihc the Meeting is to be added
required: true
schema:
type: string
- in: path
name: type
description: Type of the Meeting
required: true
schema:
type: string
- in: path
name: scheduled_start_time
description: Start time of
required: true
schema:
type: string
format: date-time
- in: path
name: scheduled_duration
description: Duration
required: true
schema:
type: integer
example: 60
- in: path
name: timezone
description: TimeZone of the event LU table
required: true
schema:
type: string
- in: path
name: region
description: Region from Zoom
required: true
schema:
type: integer
example: 1
- in: path
name: acquisition_type
description: To be added from GM
required: true
schema:
type: integer
example: 0
- in: path
name: audience_capacity
description: To be added for capacity
required: true
schema:
type: integer
- in: path
name: event_expiration_months
description: the month it expires on.
required: true
schema:
type: integer
example: 3
responses:
200:
description: This would be the response.
content:
application/json;charset=utf-8:
schema:
type: array
items:
properties:
scheduled_duration:
type: integer
example: 30
event_id:
type: integer
example: 0000000
audience_capacity:
type: integer
example: 30
folder_name:
type: string
example: Folder_Name
viewer_link:
type: string
example: https://viewer_link
scheduled_start_time:
type: string
format: date-time
example: 1541674800000
scheduled_player_close_time:
type: integer
example: 10
event_title:
type: string
[![enter image description here][1]][1]
Kindly advise on how to describe the body fields I am supposed to pass in the code.
Thanks
Got it, its passed separately in "requestbody" check here
Thanks.
In OpenApi 3 I can specify multiple return schema for the same status code.
As an example: given the endpoint /something and it can either return an ApiResultOk or ApiResultError.
(The example if from https://stackoverflow.com/a/47453822/3430316)
openapi: 3.0.0
paths:
/something:
get:
responses:
'200':
description: Result
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/ApiResultOk'
- $ref: '#/components/schemas/ApiResultError'
components:
schemas:
ApiResultOk:
type: object
properties:
result:
type: boolean
enum: [true]
token:
type: string
required:
- result
- token
ApiResultError:
type: object
properties:
result:
type: boolean
enum: [false]
errorCode:
type: string
errorMsg:
type: string
Is it possible to specify different headers for the related schemas?
(As a workaround, headers can be optional with the description when it is provided.)
I try to generate a REST API definition with Swagger and YAML,
but at $ref: '#/definitions/Token' I get the error
Bad indentation of a mapping entry
parameters:
- name: environmentID
in: query
description: id from the gamificationenvironment
required: true
type: integer
format: int32
- name: authorizationToken
in: query
description: Authorization token to create a new environment
required: true
schema:
type: object
--> Error $ref: '#/definitions/Token'
responses:
201:
description: GamificationID for the Admin
schema:
type: object
items:
$ref: '#/definitions/Environment'
default:
description: Unexpected error
schema:
$ref: '#/definitions/Error'
definitions:
Token:
required:
- authentificationKey
- user
properties:
authentificationKey:
type: string
senderID:
type: integer
format: int32
user:
type: string
type: integer
format: int64
Error:
type: object
properties:
code:
type: integer
format: int32
message:
type: string
fields:
type: string
My Question is:
Why does the Mapping with $ref is working at the responses and
at the paramets I get an error ?
This part is syntactically incorrect:
required: true
schema:
type: object
$ref: '#/definitions/Token'
schema: should be at same level as required:.
I've take the allOf examples in https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#models-with-composition, and applied them to parameters schema and responses schema. My allOf parameters and responses, however, show as undefined. When just using Pet instead of Cat, it works fine. Please let me know how to use Swagger's allOf
swagger: '2.0'
# This is your document metadata
info:
version: "0.0.0"
title: <enter your title>
# Describe your paths here
paths:
/test1:
# This is a HTTP operation
post:
description: bla bla
parameters:
- name: Pet
required: true
in: body
description: The Pet.
schema:
$ref: '#/definitions/Pet'
# Expected responses for this operation:
responses:
# Response code
200:
description: Successful response
schema:
$ref: '#/definitions/Pet'
/test2:
# This is a HTTP operation
post:
description: bla bla
parameters:
- name: Cat
required: true
in: body
description: The cat.
schema:
$ref: '#/definitions/Cat'
# Expected responses for this operation:
responses:
# Response code
200:
description: Successful response
schema:
$ref: '#/definitions/Cat'
definitions:
Pet:
type: object
discriminator: petType
properties:
name:
type: string
petType:
type: string
required:
- name
- petType
Cat:
description: A representation of a cat
allOf:
- $ref: '#/definitions/Pet'
- type: object
properties:
huntingSkill:
type: string
description: The measured skill for hunting
default: lazy
enum:
- clueless
- lazy
- adventurous
- aggressive
required:
- huntingSkill
A type field is missing in Cat Definitions Object and therefore swagger-editor shows undefined.
Add type: object as follow can fix it:
Cat:
type: object
description: A representation of a cat
allOf: