In swaggerhub I am trying to build a restful API. For which I have created n number of POJOs for request. I would like to represent them as references in other POJO example:
ClientInformation:
type: object
schema:
$ref: '#/definitions/EditClient'
$ref: '#/definitions/OtherDetails' #Duplicate mapping key error I see at this line
properties:
notes:
type: string
example: This is a test
description: A description
I tried , but didn't work. Kindly suggest.
If ClientInformation is a merger of the EditClient and OtherDetails schemas, you need allOf:
ClientInformation:
allOf:
- $ref: '#/definitions/EditClient'
- $ref: '#/definitions/OtherDetails'
- type: object
properties:
notes:
type: string
example: This is a test
description: A description
If ClientInformation has properties that are instances of other schemas, you can $ref the property schemas as follows:
ClientInformation:
type: object
properties:
notes:
type: string
example: This is a test
description: A description
foo:
$ref: '#/definitions/EditClient'
bar:
$ref: '#/definitions/OtherDetails'
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'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)
I'm using OpenAPI 3.0 to define an API for a service I am building. I'm running into an issue reusing schema components inside other components. For example, I have a Note object which contains a Profile object of the person who created the note. This works as expected by referencing the Profile object using the $ref keyword. The issue is when showing the example there isn't any data for the profile, and if I place the ref in the example like below it includes the actual OpenAPI block of Profile not just the example data for the Profile component.
I'm wondering if there is a way of reusing components in other components and also reusing the example set on those components?
Ex:
FullNote:
allOf:
- $ref: '#/components/schemas/BaseNote'
- type: object
title: A single note response
required:
- id
- dateCreated
- profile
properties:
id:
type: integer
format: int32
dateCreated:
type: integer
format: int64
profile:
type: object
$ref: '#/components/schemas/Profile'
example:
id: 123456789
dateCreated: 1509048083045
profile:
$ref: '#/components/schemas/Profile'
The example keyword (not to be confused with exampleS) does NOT support $ref. The whole example needs to be specified inline:
FullNote:
allOf:
- $ref: '#/components/schemas/BaseNote'
- type: object
...
example:
id: 123456789
dateCreated: 1509048083045
influencer:
prop1: value1 # <----
prop2: value2
Alternatively, you can use property-level examples - in this case tools like Swagger UI will build the schema example from property examples.
FullNote:
allOf:
- $ref: '#/components/schemas/BaseNote'
- type: object
...
properties:
id:
type: integer
format: int32
example: 123456789 # <----
dateCreated:
type: integer
format: int64
example: 1509048083045 # <----
profile:
# This property will use examples from the Profile schema
$ref: '#/components/schemas/Profile'
Profile:
type: object
properties:
prop1:
type: string
example: value1 # <----
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
]
}