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?
Related
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
I am trying to define my API using OpenAPI version 3.0. I am trying to generate a YAML file which has four maps, and each map contains a different information. How can I create a YAML file to achieve that goal? I know that my components are not right because of which I am not getting the right result.
Request body should be like this:
[
UserInformation{FirstName, LastName},
AddressInformation{Phone, Address},
ContactInformation{Email, Phone}
]
openapi: 3.0.0
info:
version: 1.0.0
title: 'INPUT-FORM-API'
paths:
/api/v1/test/healthcheck:
get:
summary: Health check for the test api services. Used Internally
operationId: Externalhealthcheck
description: healthcheck for the test services status.
responses:
'200':
description: This status is always returned when service is Ok.
content:
application/json:
schema:
$ref: '#/components/schemas/HealthcheckObject'
/api/v1/test/newformentry:
post:
summary: End Point to insert data into the new table.
operationId: NewFormEntry
description: EndPoint to insert data for new form.
requestBody:
content:
application/json:
schema:
items:
$ref: '#/components/schemas/NewFormEntry'
responses:
'200':
description: This status is always returned when service is Ok.
content:
application/json:
schema:
$ref: '#/components/schemas/HealthcheckObject'
components:
schemas:
NewFormEntry:
$ref: '#/components/schemas/UserInformation'
$ref: '#/components/schemas/AddressInformation'
$ref: '#/components/schemas/ContactInformation'
$ref: '#/components/schemas/MessageFromBene'
UserInformation:
required:
- FirstName
- LastName
properties:
FirstName:
type: string
LastName:
type: string
AddressInformation:
required:
- StreetAddress
- City
- State
- ZipCode
properties:
StreetAddress:
type: string
StreetAddress2:
type: string
City:
type: string
State:
type: string
ZipCode:
type: integer
format: int64
ContactInformation:
required:
- PhoneNumber
- Email
properties:
PhoneNumber:
type: integer
format: int64
maximum: 9
Email:
type: string
HomePhone:
type: integer
format: int64
maximum: 9
Cell:
type: integer
format: int64
maximum: 9
WorkPhone:
type: integer
format: int64
maximum: 9
MessageFromBene:
required:
- Message
properties:
PhoneNumber:
type: integer
format: int64
maximum: 9
Message:
type: string
HealthcheckObject:
required:
- Status
- ErrorMessage
properties:
Status:
type: string
ErrorMessage:
type: string
So the NewFormEntry schema must be an array containing 3 objects, where the 1st object must be UserInformation, the second object must be AddressInformation, and the 3rd object mube be ContactInformation. This is like a tuple, i.e. an ordered sequence of elements where each element has a specfic type. Tuple definitions are slightly different in different OpenAPI versions.
OpenAPI 3.1
If or when you migrate to OAS 3.1, such an array can be defined using prefixItems. This keyword specifies the schema for each element position (in other words, it specifies the order of elements in the array):
components:
schemas:
NewFormEntry:
type: array
prefixItems:
- $ref: '#/components/schemas/UserInformation' # type of the 1st element
- $ref: '#/components/schemas/AddressInformation' # type of the 2nd element
- $ref: '#/components/schemas/ContactInformation' # type of the 3rd element
minItems: 3
maxItems: 3
additionalItems: false # can be omitted if `maxItems: 3` is specified
OpenAPI 3.0
In OAS 3.0, you can define the array length (i.e. 3 items) and the possible types of array items (i.e. each item can be either A, B, or C), but there's no way to define a specific order of objects in the array. So the most you can do is this:
components:
schemas:
NewFormEntry:
type: array
items:
oneOf:
- $ref: '#/components/schemas/UserInformation'
- $ref: '#/components/schemas/AddressInformation'
- $ref: '#/components/schemas/ContactInformation'
minItems: 3
maxItems: 3
Note that this definition allows arbitrary order of objects in the array and also multiple instances of the same object (e.g. [UserInformation, UserInformation, UserInformation]). You might want to implement additional backend validations to verify the desired order of objects in this array.
How can I reference from one description of an component to another?
comparam01:
in: query
name: comparam01
schema:
type: string
description: |
Any text.
comparam02:
in: query
name: comparam02
schema:
# that's working!
$ref: '#/components/parameters/comparam01/schema'
description:
# Swagger says: Error (should be a string)
$ref: '#/components/parameters/comparam01/description'
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 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!