I want to return a list of elements, by only providing the IDs. Then I want to tell the user that they can retrieve the individual details by calling the get element api.
Problem is I'm not sure about the syntax, can you check this out?
paths:
/pet:
get:
summary: Get all pets
description: Returns the list of all pets
operationId: getAllPets
tags:
- pet
parameters:
- name: full
in: query
description: whatever return all or part
required: false
schema:
type: boolean
responses:
'200':
description: The list of all pets in the store, can be full or only first level with partials
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Pet'
links:
getPetDetails:
description: in case of partial you can use this operation to retrieve individual pet details
operationId: getPetById
parameters:
petId: '$response.body#/id' #...but the response body is an array!
Related
I want to extend the "200SuccessDefault" response with a schema or example.
paths:
/home:
...
responses:
200:
$ref: '#/components/responses/200SuccessDefault'
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/PieChartElement'
examples:
PieChart:
$ref: '#/components/examples/PieChart_1'
This approach runs into an error, the schema and examples fields are ignored:
Sibling values alongside $refs are ignored. To add properties to a $ref, wrap the $ref into allOf, or move the extra properties into the referenced definition (if applicable).
I tried allOf:
paths:
/home:
responses:
200:
allOf:
- $ref: '#/components/responses/200SuccessDefault'
- content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/PieChartElement'
examples:
PieChart:
$ref: '#/components/examples/PieChart_1'
This approach runs into the error:
should NOT have additional properties additionalProperty: allOf
should have required property 'description' missingProperty: description
You cannot extend a referenced response object. But, you can use a shared schema object and extend it utilizing allOf within schema.
Inside allOf you can put:
your $ref
a new type extending your default response
If you want to give an example of an entire extended response (JSON), just put it into "application/json".
An example of OpenAPI would be:
"202":
description: Extended response sample
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/application"
- type: object
properties:
anotherProperty:
type: string
maxLength: 200
example: "Property example"
example: {id: 1234, anotherProperty: "Hello"}
I am using Enums as parameter in api. But it results in the parameters being surrounded by quotes.
In the image below it shows how %22 surrounds the parameter summary - %22summary%22 as I select it from drop down.
How can I avoid adding quotes to the parameter ?
/v1/metrics/{profile}:
parameters:
- $ref: "#/components/parameters/profile"
get:
summary: Get list of field or summary profile metrics
description: Retrieves list of metrics for field or summary profile
tags:
- profile-metrics
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: "#/components/schemas/ProfileMetrics"
'400':
$ref: "#/components/responses/BadRequest"
'404':
$ref: "#/components/responses/NotFound"
default:
$ref: "#/components/responses/UnexpectedError"
profile parameter schema
profile:
name: profile
description: profile type either field or summary
schema:
type: string
enum: [ field, summary ]
in: path
required: true
Any help is appreciated
This question already has answers here:
How to exclude a property from a referenced schema?
(1 answer)
How to reuse swagger definitions and remove some of the parameters in it? [duplicate]
(1 answer)
How to make a field in a definition required for some operations and not others
(3 answers)
Closed 9 months ago.
I created a swagger containing a get and a put, where in the first I call an element ("MyCar") and in the second I update the license plate. Being the same object, how can I make sure that in the swagger put it can show only the plate instead of all the fields of the object?
'/example/car/{carId}':
get:
summary: Get a Car by Id
description: Get a car
operationId: getCar
tags:
- Car
parameters:
- in: path
name: carId
required: true
description: carID
schema:
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/MyCar'
[...]
put:
summary: Update car plate
description: update a plate by carID
operationId: updatePlate
tags:
- Car
parameters:
- in: path
name: carId
required: true
description: CarID to save
schema:
type: string
requestBody:
description: The new plate to create
content:
application/json:
schema:
$ref: '#/components/schemas/MyCar'
[...]
MyCar:
type: object
properties:
id:
type: string
owner:
type: string
plate:
type: string
is there a way to show only the license plate in the put without showing the whole object?
I'm reading this: OpenAPI 3.0 Tutorial
If I'm looking on one of the examples, there are some things I can't understand
openapi: 3.0.0
info:
version: 1.0.0
title: Simple API
description: A simple API to illustrate OpenAPI concepts
servers:
- url: https://example.io/v1
components:
securitySchemes:
BasicAuth:
type: http
scheme: basic
security:
- BasicAuth: []
paths:
/artists:
get:
description: Returns a list of artists
parameters:
- name: limit
in: query
description: Limits the number of items on a page
schema:
type: integer
- name: offset
in: query
description: Specifies the page number of the artists to be displayed
schema:
type: integer
responses:
'200':
description: Successfully returned a list of artists
content:
application/json:
schema:
type: array
items:
type: object
required:
- username
properties:
artist_name:
type: string
artist_genre:
type: string
albums_recorded:
type: integer
username:
type: string
'400':
description: Invalid request
content:
application/json:
schema:
type: object
properties:
message:
type: string
# ----- Added lines ----------------------------------------
post:
description: Lets a user post a new artist
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- username
properties:
artist_name:
type: string
artist_genre:
type: string
albums_recorded:
type: integer
username:
type: string
responses:
'200':
description: Successfully created a new artist
'400':
description: Invalid request
content:
application/json:
schema:
type: object
properties:
message:
type: string
# ---- /Added lines ----------------------------------------
Why the response of /get contains: required: username ? what is the meaning of this ?
if I don't want basic authentication, can I remove this line ?
Why do we need to write required: true for the requestBody under the post ? It's not basic that post contains body ?
The answer of your questions are:
Why the response of /get contains: required: username? what is the meaning of this? if I don't want basic authentication, can I remove this line?
Ans: Username is required means it's mandatory, i.e. response must contain this field with some value in it. It's not associated with basic authentication. So, yes you can remove that line if it is not used by the application.
Why do we need to write required: true for the requestBody under the post? It's not basic that post contains body?
Ans: Required: true is not mandatory to write here. It's an optional field and post must have a request body. Yeah, you are right. It's a basic thing that posts must have to contain the request body.
If you can have any confusion further then let me know. Thanks
I'm using SwaggerHub with OpenAPI 3 to define an API. One route GET /foo/{id], should return the foo object of a given id, with its associated bar objects. The API will return something like: {id: 4, name: 'test', bars: [{id: 53, name: 'barName1'}, {id: 87, name: 'barName2'}]}. I.e. there is a many-to-many relationship between foo and bar.
How do I describe this in OpenAPI 3 syntax? I have tried using the anyOf property. So far I have:
paths:
/foo/{id}:
get:
parameters:
- name: id
in: path
required: true
schema:
type: integer
responses:
'200':
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Foo'
anyOf:
- $ref: '#/components/schemas/Bar'
But this doesn't appear to show the correct schema in the UI (there is no mention of Bar in the UI).
You don't need anyOf. anyOf indicates an alternative ("either Foo or Bar"), whereas you have a usual nested structure - an object Foo with the property bars that is an array of Bars. This can be described as:
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/Foo'
components:
schemas:
Foo:
type: object
properties:
bars:
type: array
items:
$ref: '#/components/schemas/Bar'
required:
- bars
Bar:
...