I have a problem .
I created openApi request and I want to send to request not empty body
/test
post:
.
.
.
requestBody:
required:true
TestRequest
type: object
required:
- testName
properties:
testName:
type: string
description: Test
I can send a request empty body like
{
} on postman.
How can i solve this problem .
Your post definition states that a body is required. However, you have not defined what the shape of the data is that must go into that body.
Here is an example that assumes your TestRequest is defined inside components/schemas.
paths:
/test:
post:
description: An example referencing TestRequest
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/TestRequest'
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'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 am getting the error below:
Declared path parameter "imageId" needs to be defined as a path
parameter at either the path or operation level
This is the snapshot of my swagger definition
'/api/v1/images/{unitnumber}/{type}/{imageId}':
delete:
tags:
- Images
summary: 'Summary'
description: "Description"
operationId: DeleteImage
consumes: []
produces:
- application/json
parameters:
- name: unitnumber
in: path
required: true
type: string
- name: type
in: path
required: true
type: string
- name: imageId
in: query
required: false
type: string
responses:
'400':
description: Bad Request
schema:
$ref: '#/definitions/ErrorResponse'
'401':
description: Unauthorized
schema:
type: string
'500':
description: Server Error
schema:
$ref: '#/definitions/ErrorResponse'
I only can get rid of the error if I take the imageId and changing to path instead query which is not the intention
- name: imageId
in: path
required: true
type: string
Any idea of what I need to change to have this working?
The path string /api/v1/images/{unitnumber}/{type}/{imageId} means that imageId is a path parameter so it must be in: path.
If imageId is supposed to be a query parameter, as in /api/v1/images/{unitnumber}/{type}?imageId=..., you need to change the path string to /api/v1/images/{unitnumber}/{type}. Query parameters should not be mentioned in paths, they are defined in the parameters section alone.
You have to declare a query parameter using a question mark as follows:
/api/v1/images/{unitnumber}/{type}/{?imageId}
In Swagger 2.0 (OpenAPI spec) is there any way to specify an "example" for a request body and also specify the ref? I can do so for a response body. My case is for a certain PUT the body is a ref, but the instance you'd put would differ from the schema's example value.
- name: myObj
in: body
description: The information
required: true
schema:
$ref: '#/definitions/SomeObject'
example: 'some string that conforms to my ref'
In OpenAPI 2.0 - no, not really. $ref overwrites any adjacent keywords, so the example will be ignored. Some tools support x-example or x-examples for parameters, so depending on your tool you might be able to use
- name: myObj
in: body
description: The information
required: true
schema:
$ref: '#/definitions/SomeObject'
x-example:
property1: value1
property2: value2
or
- name: myObj
in: body
description: The information
required: true
schema:
$ref: '#/definitions/SomeObject'
x-examples:
application/json:
property1: value1
property2: value2
or something similar.
What you want is possible in OpenAPI 3.0:
openapi: 3.0.0
...
paths:
/something:
put:
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/SomeObject'
example:
property1: value1
property2: value2
This is supported in Swagger UI 3.17.4 and later.
I'm documenting an API on swagger.io. When I try to define session_token as a required string property in the header, I get the error:
My definition matches the sample in the documentation so I'm not sure what
s causing the issue.
Snippet
/customerVerifyLogin:
post:
summary: Validate verification code sent to authenticate login. Returns session_token
parameters:
- name: Authorization
in: header
type: string
required: true
default: Basic YWRtaW46WDRCbzViWnZTamlXU0hoZDFMOGNpUHkyUERzekUwU3I=
- name: session_type
in: header
type: string
enum:
- android
- ios
required: true
- name: VerificationCode
in: body
type: string
required: true
description:
schema:
type: object
properties:
phone:
type: string
description: The mobile number to which the verification was sent.
device_id:
type: string
description: ID that uniquely identifies the device
code:
in: body
type: integer
format: int32
required: true
description: Verification code to be validated.
responses:
200:
description: Customer logged-in successfully.
schema:
$ref: '#/definitions/Customer'
tags:
- Verification
- Login
a couple errors in your document:
VerificationCode shows type: string and schema:. For a body param (in: body), you can only use schema. Just delete the type: string.
Your definition for the property code has some unwanted fields:
Remove in: body. That's probably a copy/paste error
Remove required: true. That's not the correct way to say a property is required, move it to a sibling of the properties object like such:
required:
- code
properties:
code:
# the rest of your definition