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)
Related
We have an openapi definition as follow:
filterParameter:
name: addCartEntriesByFilterParameter
in: query
schema:
type: object
required:
- "applicationCode"
properties:
applicationCode:
type: string
[...others]
that is used in
/api/v1/applications/{applicationCode}/filtered:
put:
tags:
- Tag
operationId: byFilter
summary: Add filters
parameters:
- $ref: '#/components/parameters/applicationCode'
- $ref: '#/components/parameters/filterParameter'
responses:
"400":
$ref: '#/components/responses/400BadRequest'
"404":
$ref: '#/components/responses/404NotFound'
"200":
$ref: '#/components/responses/Response'
We would like to use only one single DTO as parameter, but we must declare two because one is a "path" param and others are "query" params. Is there a way of include all that params, "path" and "queries", in one single object when is received by Spring Boot controller?
Desired definition could be something like this, without duplicated "applicationCode" param in path and query:
/api/v1/applications/{applicationCode}/filtered:
put:
tags:
- Tag
operationId: byFilter
summary: Add filters
parameters:
- $ref: '#/components/parameters/filterParameter'
responses:
"400":
$ref: '#/components/responses/400BadRequest'
"404":
$ref: '#/components/responses/404NotFound'
"200":
$ref: '#/components/responses/Response'
Thanks in advance
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}:
...
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"}
# ]
# }
# ]
# }
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
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
]
}