How can I access to an specific definition's property? I need in my 200's response to show an property in the "schema" node, not the whole "definition".
Here is the Yaml code:
paths:
/user/{user_id}:
get:
description: Devuelve un `user` pasándole su `user_id`.
produces:
- application/json
parameters:
- name: user_id
in: path
description: Identificador del `user`.
required: true
type: string
format: VarChar (255)
responses:
'200':
description: Ok
schema:
$ref: "#/definitions/User"
definitions:
User:
properties:
user_id:
type: integer
format: BigInt
description: Identificador del usuario.
email:
type: string
format: VarChar (255)
description: Email del usuario
pwd:
type: string
format: VarChar (255)
description: Password del usuario.
I mean, I just need something like this:
responses:
'200':
description: Ok
schema:
$ref: "#/definitions/User/user_id"
Any thought?
The response needs to be a proper schema. And your reference needs to follow the elements in the actual object.
If you do this:
'200':
description: Ok
schema:
$ref: "#/definitions/User/properties/user_id"
It should work fine.
Related
I am using Open API 3.0 to generate the code.
Below is Open API specification:
spec.yml:
openapi: 3.0.0
info:
version: 1.0.0
title: Store API
description: A store API to get store and related department information
termsOfService: http://www.***.com/xml,
contact:
name: MTAMP Support,
url: http://www.****.com/xml,
email: mtamp#mt.com
paths:
/api/stores:
get:
summary: To get all stores
tags:
- Stores
description: To get all store and department information
operationId: getStores
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/StoresDTO'
/api/stores/{storeId}:
parameters:
- in: path
name: storeId
required: true
schema:
type: integer
format: int64
description: Pass a store Id as a parameter
get:
summary: To get store infomation based on storeId. When you pass storeId as request related store information along with department will get returned.
tags:
- Stores
description: To get store information based on storeId
operationId: getStoresById
x-mtampException:
- throws com.mt.mtamp.storeservice.exception.ResourceNotFoundException
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/StoresDTO'
/api/stores/{storeId}/regions/{regionId}:
parameters:
- in: path
name: storeId
required: true
schema:
type: integer
format: int64
description: Pass a store Id as a parameter
- in: path
name: regionId
required: true
schema:
type: integer
format: int64
description: Pass a region Id as a parameter
get:
summary: To get store infomation based on regionId. When you pass region as request related store information will get returned.
tags:
- Stores
description: To get store information based on regionId.
operationId: getStoresByRegionId
x-mtampException:
- throws com.mt.mtamp.storeservice.exception.ResourceNotFoundException
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/StoresDTO'
/api/departments/{departmentId}/stores/{storeId}:
parameters:
- in: path
name: storeId
required: true
schema:
type: integer
format: int64
description: Pass a department Id as a parameter
- in: path
name: departmentId
required: true
schema:
type: integer
format: int64
description: Pass a store Id as a parameter
get:
summary: To get department infomation based on storeId. When you pass store Id as request related department information will get returned.
tags:
- Departments
description: To get department information based on storeId.
operationId: getDepartmentsByStoreId
x-mtampException:
- throws com.mt.mtamp.storeservice.exception.ResourceNotFoundException
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/DepartmentsDTO'
/api/regions/{regionId}/customer/{customerId}:
parameters:
- in: path
name: customerId
required: true
schema:
type: integer
format: int32
description: Pass a customer Id as a parameter
- in: path
name: regionId
required: true
schema:
type: integer
format: int64
description: Pass a region Id as a parameter
get:
summary: To get region based on customer Id.
tags:
- Regions
description: To get region information based on customer Id.
operationId: getRegionByCustomerId
x-mtampException:
- throws com.mt.mtamp.storeservice.exception.ResourceNotFoundException
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/RegionsDTO'
components:
schemas:
StoresDTO:
required:
- storeName
- storeLocation
properties:
storeId:
type: integer
format: int64
example: 1
storeName:
type: string
example: FreshPro
storeLocation:
type: string
example: Germany
departments:
type: array
items:
$ref: '#/components/schemas/DepartmentsDTO'
DepartmentsDTO:
required:
- departmentId
- departmentName
properties:
departmentId:
type: integer
format: int64
example: 42
departmentName:
type: string
example: Vegetables
storeId:
type: integer
format: int64
example: 34
RegionsDTO:
required:
- regionId
- regionName
properties:
regionId:
type: integer
format: int64
example: 22
regionName:
type: string
example: Fresh Pro
customerId:
type: integer
example: 19
stores:
type: array
items:
$ref: '#/components/schemas/StoresDTO'
Generated Code:
#RequestMapping(
method = RequestMethod.GET,
value = "/api/stores/{storeId}/regions/{regionId}",
produces = { "application/json" }
)
ResponseEntity<List<StoresDTO>> getStoresByRegionId(
#Parameter(name = "storeId", description = "Pass a store Id as a parameter", required = true) #PathVariable("storeId") Long storeId,
#Parameter(name = "regionId", description = "Pass a region Id as a parameter", required = true) #PathVariable("regionId") Long regionId
)throws com.mt.mtamp.storeservice.exception.ResourceNotFoundException;
Here when I load the swagger for example for service /api/stores/{storesId}/regions/{regionId}, I am seeing the response showing stores and departments object.
This API returns a list of store object but in swagger it showing be single store object.
Can I know how to fix this swagger and Openapi issue
This question already has answers here:
How to return an array of objects in SwaggerHub?
(2 answers)
Closed 4 years ago.
I have this schema defined:
User:
type: object
required:
- id
- username
properties:
id:
type: integer
format: int32
readOnly: true
xml:
attribute: true
description: The user ID
username:
type: string
readOnly: true
description: The username
first_name:
type: string
description: Users First Name
last_name:
type: string
description: Users Last Name
avatar:
$ref: '#/components/schemas/Image'
example:
id: 10
username: jsmith
first_name: Jessica
last_name: Smith
avatar: image goes here
xml:
name: user
Works great. The GET /user/{id} call displays the sample data just fine.
I have a second schema that creates an array of the above schema:
ArrayOfUsers:
type: array
items:
type: object
required:
- id
- username
properties:
id:
type: integer
format: int32
xml:
attribute: true
description: The user ID
username:
type: string
description: The username
first_name:
type: string
description: Users First Name
last_name:
type: string
description: Users Last Name
avatar:
$ref: '#/components/schemas/Image'
This also works great. The GET /user call displays the proper structure in an array just fine.
But I'd rather not define this schema twice.
I would like to create a schema that utilizes the first one and stick in an array.
I have failed in this attempt.
I tried it this way:
UserArray:
type: array
items:
type: object
required:
- id
- username
properties:
things:
type: array
items:
oneOf:
- $ref: '#/components/schemas/User'
This attempt gives me an empty array:
[
{}
]
This is not my desired result.
Any hints on this?
An array of User objects is defined as follows:
UserArray:
type: array
items:
$ref: '#/components/schemas/User'
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}:
...
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
]
}