Swagger using the same model but different examples - yaml

My API can retun 200 ok or 400, an error occurred. I want them both to use the same model but different examples. In my code below, I want my 200 Info to say something like "All ok" and 400's Info "Not ok".
responses:
'200':
description: >-
Invoice received for processing but beware of potentional warnings
and information
schema:
$ref: '#/definitions/Response'
'400':
description: Invoice could not be processed due to fatal errors
schema:
$ref: '#/definitions/Response'
Response:
type: object
properties:
Info:
type: string
information
Messages:
type: object
properties:
Fatal:
type: array
items:
type: object
Warning:
type: array
items:
type: object
Information:
type: array
items:
type: object

In OpenAPI 2.0, responses support the examples keyword to specify response examples for different HTTP status codes and media types.
responses:
'200':
description: >-
Invoice received for processing but beware of potential warnings
and information
schema:
$ref: '#/definitions/Response'
examples:
application/json:
Info: OK
# Or using JSON syntax for the example value:
# application/json: {"Info": "OK"}
'400':
description: Invoice could not be processed due to fatal errors
schema:
$ref: '#/definitions/Response'
examples:
application/json:
Info: Oops
Messages:
Fatal:
- Houston, we have a problem
# Or using JSON syntax for the example value:
# application/json:
# {
# "Info": "Oops",
# "Messages": [
# {
# "Fatal": [
# {"Custom error": "Houston, we have a problem"}
# ]
# }
# ]
# }

Related

OpenAPI: overriding a reference, referencing a single field

I'm using two files :
common.yaml contains :
components:
schemas:
GenericError:
type: object
properties:
code:
description: The error code.
type: integer
message:
description: The error description.
type: string
details:
description: Optional details.
type: object
examples:
Bamboozled:
value:
code: 10
message: Bamboozled
details: You've been bamboozled
services.yaml` contains :
paths:
/logistic:
post:
description: Logistic
responses:
403:
description: Forbidden
content:
application/json:
schema:
$ref: '../common.yaml#/components/schemas/GenericError'
examples:
Bamboozled:
value:
$ref: '../common.yaml#/components/examples/Bamboozled/value'
In services.yaml, I would like to override the details field. I tried the following :
examples:
Bamboozled:
value:
$ref: '../common.yaml#/components/examples/Bamboozled/value'
details: my custom details
but this doesn't work, it will render :
{
"$ref":
"#/paths/~1logistic/post/responses/403/content/application~1json/examples/Bamboozled/value",
"details": "my custom details"
}
Is there a way I can override it correctly ?
Alternatively, can I reference only specific fields ? So I would have services.yaml something such as :
examples:
Bamboozled:
value:
$ref: '../common.yaml#/components/examples/Bamboozled/value/code'
$ref: '../common.yaml#/components/examples/Bamboozled/value/message'
details: my custom details
(this doesn't work)

swagger should not have additional properties using OpenAPI (3.0.0)

I have looked at the questions that were already asked but none of them have been able to solve my issue.
https://stackoverflow.com/questions/45534187/path-and-formdata-paramter-at-the-same-time
https://stackoverflow.com/questions/50562971/swagger-editor-shows-the-schema-error-should-not-have-additional-properties-e
https://stackoverflow.com/questions/48283801/swagger-3-0-schema-error-should-not-have-additional-properties
I am using OpenAPI 3.0.0. I get the following issue at line 6. I have gone through multiple times and indented, moved things around, and started over. I have used the swagger documentation but I still am getting this issue. I will post the yaml below. Any hints will be appreciated.
Error:
should not have additional properties:
additionalProperty: /author/author{id}
# openapi: 3.0.0
# info:
# version: 0.0.1
# title: Author API
# description: Author API documentation
openapi: 3.0.0
info:
title: Author API
description: Author API
version: 0.0.1
servers:
- url: 'http://localhost:8080/'
description: Local dev server
# post new author done
# find author {id} done
# get all author done
# update author {id} done
# delete author {id} done
paths:
/author:
post:
summary: Add a author to database
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Author'
responses:
'201':
description: return the author to the user with the id attached
content:
application/json:
schema:
$ref: '#/components/schemas/Author'
get:
summary: Get all the authors in the database
responses:
'200':
description: Return all the authors in the database
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Author'
/author/{authorId}:
update:
summary: update the author with the id
parameters:
- name: authorId
in: path
required: true
description: Id of the author to update
schema:
type: integer
responses:
'200':
description: Return just the author at that id
content:
application/json:
schema:
$ref: '#/components/schemas/Author'
get:
summary: get the author with the specific id
paramaters:
- name: authorId
in : path
required: true
description: Id of the author to retrieve
schema:
type: integer
responses:
'200':
description: Return just the author at that id
content:
application/json:
schema:
$ref: '#/components/schemas/Author'
delete:
summary: Remove a author by the given Id
parameters:
- name: authorId
in: path
required: true
description: Id of the author to delete
schema:
type: integer
responses:
'200':
description: The author was successfully removed
components:
schemas:
Author:
type: object
properties:
authorId:
type: integer
firstName:
type: string
lastName:
type: string
street:
type: string
city:
type: string
state:
type: string
postalCode:
type: string
phone:
type: string
email:
type : string
Add two spaces before /author/{authorId}, so that this line has the same indentation as /author. YAML requires proper indentation of nested items.
paths:
/author:
...
/author/{authorId}:
...

how to pass multi value query params in swagger

I have following service in swagger.yml. The service is written so that page_id can be passed multiple times. e.g /pages?page_id[]=123&page_id[]=542
I checked this link https://swagger.io/specification/ but couldnt understand how could i update yml so i could pass id multiple times.
I see that i have to set collectionFormat but dont know how.
I tried updating it like below but no luck https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md.
it generates url like 'http://localhost:0000/pages?page_id=123%2C%20542`
'/pages':
get:
tags:
-
summary: get the list of pages
operationId: getPages
produces:
- application/json
parameters:
- name: page_id
in: query
description: some description
required: false
type: string
collectionFormat: multi
- name: page_detail
in: query
description: some description
required: false
type: string
responses:
'200':
description: OK
'401':
description: Authentication Failed
'404':
description: Not Found
'503':
description: Service Not Available
You are almost there. Name the parameter page_id[], make it type: array and use collectionFormat: multi:
parameters:
- name: page_id[]
in: query
description: some description
required: false
type: array
items:
type: string # or type: integer or whatever the type is
collectionFormat: multi
Note that the requests will be sent with the [ and ] characters percent-encoded as %5B and %5D, because they are reserved characters according to RFC 3986.
http://example.com/pages?page_id%5B%5D=123&page_id%5B%5D=456
From the docs:
parameters:
- name: id
in: path
description: ID of pet to use
required: true
schema:
type: array
style: simple
items:
type: string
You have to define the parameter as array.
How to add default values to the query parameter of type array:
parameters:
- name: 'liabilityType[]'
in: query
description: liabilityType filters the servicers list according to liability types.
required: false
schema:
type: array
items:
type: string
collectionFormat: multi
value:
- CAR
- HOUSE
I have attached a picture of how this code would look like in Swagger UI
[1]: https://i.stack.imgur.com/MSSaJ.png

How to define array-of-objects as parameter?

I am quite new to Swagger, so this might be a basic question.
I am able to create .yml file for an API which takes an array of integers as parameter, as follows:
Add samples
---
tags:
- MY API
parameters:
- name: my_id
in: path
type: integer
required: true
description: Some des
- name: body
in: body
schema:
id: add_samples
required:
- sample_ids
properties:
sample_ids:
type: array
items:
type: integer
description: A list of sample ids to be added
responses:
'200':
description: Added samples.
'400':
description: Error adding samples.
This is what I send to the above API and everything works fine:
{"sample_ids": [475690,475689,475688]}
Now, instead of an array of integers, if I want to use some complex object as parameter, how to do it?
E.g. If this is what I want to send:
{"sample_ids": [{
"sample_id": "7",
"some_prop": "123"
},
{
"sample_id": "17",
"some_prop": "134"
}]}
How should the .yml file look? I have tried something like this and it doesn't seem to work:
Add sample
---
tags:
- Samples API
models:
Sample:
id: Sample
properties:
sample_id:
type: string
default: ""
description: The id for this sample
some_prop:
type: integer
description: Some prop this sample
parameters:
- name: body
in: body
schema:
id: add_sample
required:
- sample_ids
properties:
samples:
type: array
description: A list of samples to be added
items:
$ref: Sample
responses:
'201':
description: Created a new sample with the provided parameters
'400':
description: SOME ERROR CODE
This one seems to work, mostly:
Add sample
---
tags:
- Samples API
models:
Sample:
id: Sample
properties:
sample_id:
type: string
default: ""
description: The id for this sample
some_prop:
type: integer
description: Some prop this sample
parameters:
- name: body
in: body
schema:
id: add_sample
required:
- sample_ids
properties:
samples:
type: array
description: A list of samples to be added
items:
$ref: Sample
responses:
'201':
description: Created a new sample with the provided parameters
'400':
description: SOME ERROR CODE
Now only problem is, in the Swagger UI, it is not showing member variables and their default values. Rather is showing it as null:
{
"samples": [
null
]
}

Not a valid parameter definition , Swagger 2.0

i am new to swagger and following is the code i was trying to edit in the online editor. But it is displaying an error which says "Not a valid parameter definition" at the parameters field.
# Example YAML to get you started quickly.
# Be aware that YAML has indentation based scoping.
# Code completion support is available so start typing for available options.
swagger: '2.0'
# This is your document metadata
info:
version: "0.0.0"
title: <test>
# Describe your paths here
paths:
# This is a path endpoint. Change it.
/test:
# This is a HTTP operation
post:
# Describe this verb here. Note: you can use markdown
description: Pass list of input parameter.
# This is array of GET operation parameters:
operationId: test
produces:
- application/json
- application/xml
- text/xml
- text/html
parameters:
-
name: value
in: body
description: Input parameter list
required: true
schema:
type: array
items:
type: object
properties:
Name:
type: string
Age:
type: integer
format: int32
Address:
type: string
Company:
type: string
WorkExperience:
type: integer
format: int32
# Expected responses for this operation:
responses:
# Response code
200:
description: Successful response
# A schema describing your response object.
# Use JSON Schema format
schema:
title: ArrayOfPersons
type: array
items:
title: Person
type: object
properties:
name:
type: string
single:
type: boolean
The following error is displayed in the swagger previewer
Swagger Error
Not a valid parameter definition
Jump to line 28
Details
Object
code: "ONE_OF_MISSING"
params: Array [0]
message: "Not a valid parameter definition"
path: Array [5]
schemaId: "http://swagger.io/v2/schema.json#"
inner: Array [2]
level: 900
type: "Swagger Error"
description: "Not a valid parameter definition"
lineNumber: 28
This is an code intending error.
schema:
type: array
items:
type: object
properties:
The "type: array" definition in the schema field was not indented properly.
parameters:
-
name: value
in: body
description: Input parameter list
required: true
schema:
type: array
items:
type: object
properties:
Name:
type: string
Age:
type: integer
format: int32
Address:
type: string
Company:
type: string
WorkExperience:
type: integer
format: int32

Resources