When using the following swagger, the resulting endpoint has an example response that doesn't align with what I believe the swagger (and the models) dictate.
The swagger:
components:
examples: {}
headers: {}
parameters: {}
requestBodies: {}
responses: {}
schemas:
SubSubData:
type: object
properties:
subSubDataProp:
type: string
SubData:
allOf:
- $ref: '#/components/schemas/SubSubData'
- type: object
properties:
subDataProp:
type: string
Data:
allOf:
- $ref: '#/components/schemas/SubData'
- type: object
properties:
dataProp:
type: string
ExampleResponse:
type: object
properties:
data:
$ref: '#/components/schemas/Data'
info:
title: __PROJECT_NAME__
version: 1.0.0
description: |
Add your Swagger description here.
license:
name: ISC
contact:
name: Me
openapi: 3.0.0
paths:
/example:
get:
operationId: GetData
responses:
'200':
description: Ok
content:
application/json:
schema:
$ref: '#/components/schemas/ExampleResponse'
security: []
The expected response:
{
"data": {
"dataProp": "string",
"subDataProp": "string",
"subSubDataProp": "string"
}
}
Actual:
{
"data": {
"dataProp": "string"
}
}
Am I missing something? Or is this a bug in the swagger ui/openapi
It's a bug in Swagger UI:
https://github.com/swagger-api/swagger-ui/issues/5972
The workaround is to move paths before components.
openapi: "3.0.0"
info:
title: project
servers:
- url: http://example1.net/v3
- url: http://example/v3
paths:
/Pn/{PnId}/service1:
post:
summary: Pn data
description: |
can Pn the data
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/dataInfo"
application/x-www-form-urlencoded:
schema:
$ref: "#/components/schemas/dataInfo"
parameters:
- name: PnId
in: path
description: PnId
required: true
schema:
$ref: "#/components/schemas/Pn"
responses:
'200':
description: status
content:
application/json:
schema:
$ref: "#/components/schemas/dataInfoStatus"
example: infoable
default:
description: error
content:
application/json:
schema:
$ref: "#/components/schemas/Error"
components:
schemas:
Error:
type: object
properties:
code:
type: integer
message:
type: string
required:
- message
Pn:
type: integer
format: int64
dataInfo:
type: string
dataInfoStatus:
type: string
enum: [infoable, non_infoable,ignorable]
I am sending a single dataInfo in request and getting single dataInfoStatus in response, but I will like to send and array of dataInfo and get an array of dataInfo status.
I tried following:
schema:
type:array
items:
$ref: "#/components/schemas/dataInfo"
but I get
Parser error bad indentation of a mapping entry
for items. I am following this.
How can I achieve sending dataInfo in request as an array of dataInfo and getting in response an array of dataInfoStatus?
You have to add one more space between type: and array, then the error message is gone:
schema:
type: array
items:
$ref: "#/components/schemas/dataInfo"
And you can add the info.version for the version of the openapi file.
I want to write openapi specs for API which will return response as set of object or another object. I am not sure how I can achieve that I have tried many things but when I run codegen for the specs I am getting class OneOfConnectionDTOConnectionPaginatedResponseDTO with error.
I am using below code and I want Set or ConnectionPaginatedResponseDTO in the 200 response
openapi: 3.0.0
servers:
- url: /
info:
title: OIM Manage Connection
version: '1.0'
paths:
'/ManageConnection/viewUserConnection/{oimid}':
get:
tags:
- View Connection
parameters:
- description: OIMID of user
in: path
name: oimid
required: true
schema:
type: string
example: 1234
- description: content type
in: header
name: Content-Type
required: true
schema:
type: string
example: application/json
- description: Start Index of records to be fetched
in: query
name: startIndex
required: false
schema:
type: string
example: 1
- description: Start Index of records to be fetched
in: query
name: count
required: false
schema:
type: string
example: 5
responses:
'200':
description: Connection list returned
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/ConnectionDTO'
- $ref: '#/components/schemas/ConnectionPaginatedResponseDTO'
'401':
$ref: '#/components/responses/UnAuthorized'
'403':
$ref: '#/components/responses/Forbidden'
'500':
$ref: '#/components/responses/DataBaseError'
'501':
$ref: '#/components/responses/MethodError'
components:
responses:
UnAuthorized:
description: Not authorized to access the specified resource
content:
application/json:
schema:
$ref: '#/components/schemas/OIMException'
MandatoryAttributeNotPassedException:
description: Requested resource can't be accessed
content:
application/json:
schema:
$ref: '#/components/schemas/OIMException'
Forbidden:
description: Requested resource can't be accessed
content:
application/json:
schema:
$ref: '#/components/schemas/OIMException'
DataBaseError:
description: Unable to connect to database
content:
application/json:
schema:
$ref: '#/components/schemas/OIMException'
MethodError:
description: Method not implemented
content:
application/json:
schema:
$ref: '#/components/schemas/OIMException'
schemas:
ConnectionDTO:
required:
- access_type
- access_identifier
properties:
add_access_date:
type: string
format: date
access_identifier:
type: string
access_type:
type: string
PIN:
type: string
is_primary_access:
type: string
valid_state:
type: string
friendly_name:
type: string
oimid:
type: string
auth_count:
type: string
type: object
ConnectionPaginatedResponseDTO:
properties:
totalResults:
type: integer
itemsPerPage:
type: integer
startIndex:
type: integer
connections:
$ref: '#/components/schemas/ConnectionDTO'
type: object
OIMException:
properties:
errorMessage:
type: array
items:
type: string
message:
type: string
httpStatus:
type: string
code:
type: integer
type: object
I have the following swagger code addCustomer for sending a request that includes an image along with other json data. When I run code from swagger hub; it just sends json. Am I defining this right? Shouldn't it send multipart request?
post:
tags:
- customers
summary: Add a new customer to the store
description: ''
operationId: addCustomer
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/NewCustomerWithImageUrl'
application/xml:
schema:
$ref: '#/components/schemas/NewCustomerWithImageUrl'
multipart/form-data:
schema:
$ref: '#/components/schemas/NewCustomerWithImage'
description: Customer object that needs to be added to the store
required: true
NewCustomerWithImage:
type: object
allOf:
- $ref: '#/components/schemas/NewCustomer'
properties:
Image:
type: string
format: binary
Person:
type: object
required:
- first_name
properties:
first_name:
type: string
example: John
last_name:
type: string
example: Doe
email:
type: string
example: john#example.com
phone_number:
type: string
example: 555-555-5555
address_1:
type: string
example: 123 Nowhere Street
address_2:
type: string
example: Apartment 123
city:
type: string
example: Rochester
state:
type: string
example: New York
zip:
type: string
example: '14445'
country:
type: string
example: United States
comments:
type: string
example: A great customer
custom_fields:
type: object
minProperties: 0
maxProperties: 10
additionalProperties:
type: string
example:
secondary phone number: '555-555-5555'
NewCustomer:
type: object
allOf:
- $ref: '#/components/schemas/Person'
properties:
company_name:
type: string
example: PHP Point Of Sale
tier_id:
type: integer
format: uuid
example: 0
account_number:
type: string
example: '3333'
taxable:
type: boolean
example: false
tax_certificate:
type: string
example: '1234'
override_default_tax:
type: boolean
example: false
tax_class_id:
type: integer
format: uuid
example: 0
balance:
type: number
format: float
example: 22.99
credit_limit:
example: null
points:
type: integer
format: int32
example: 333
disable_loyalty:
type: boolean
example: true
amount_to_spend_for_next_point:
type: number
format: float
readOnly: true
example: 10.00
remaining_sales_before_discount:
type: integer
format: int32
readOnly: true
example: 0
xml:
name: Customer
Json sent:
{"first_name":"John","last_name":"Doe","email":"john#example.com","phone_number":"555-555-5555","address_1":"123 Nowhere Street","address_2":"Apartment 123","city":"Rochester","state":"New York","zip":"14445","country":"United States","comments":"A great customer","custom_fields":{"secondary phone number":"555-555-5555"},"company_name":"PHP Point Of Sale","tier_id":0,"account_number":"3333","taxable":false,"tax_certificate":"1234","override_default_tax":false,"tax_class_id":0,"balance":22.99,"credit_limit":null,"points":333,"disable_loyalty":true,"Image":"string"}
Swagger Hub File:
https://app.swaggerhub.com/apis/PHP-Point-Of-Sale/PHP-Point-Of-Sale/1.0#/customers/addCustomer
1) Swagger UI (which SwaggerHub uses) does not yet support form data and file upload for OpenAPI 3.0 definitions. Follow this issue for status updates: https://github.com/swagger-api/swagger-ui/issues/3641 UPD: Swagger UI now supports file uploads for OAS3.
2) If "request that includes an image along with other JSON data" means a multipart request like this –
POST /foo HTTP/1.1
Content-Type: multipart/form-data; boundary=ABCDEF123
--ABCDEF123
Content-Disposition: form-data; name="Customer"
Content-Type: application/json
{
"foo": "bar"
}
--ABCDEF123
Content-Disposition: form-data; name="Image"; filename="image1.png"
Content-Type: application/octet-steam
{…image content…}
--ABCDEF123--
then the request body definition should look like this:
requestBody:
content:
...
multipart/form-data:
schema:
type: object
properties:
Customer: # <--- name of the part in a multipart request
$ref: '#/components/schemas/NewCustomer'
Image: # <--- name of the part in a multipart request
type: string
format: binary
required:
- Customer
- Image
More information:
How to describe a multipart response using OpenAPI (Swagger)? here on SO
Special Considerations for multipart Content in the OpenAPI 3.0 Specification
Multipart Requests on swagger.io
File upload is supported in Open API v 3.0.3
Here's what my swagger.json looks like:
"/media/upload": {
"post": {
"tags": ["Media"],
"name": "Upload Media",
"description": "Uploads a Media file to the server.",
"requestBody": {
"required": true,
"content": {
"multipart/form-data": {
"schema": {
"type": "object",
"properties": {
"media": {
"type": "string",
"format": "base64"
}
}
}
}
}
}
}
}
Here's how it show up in swagger:
I want this API to produce JSON in response HTTP body.
responses:
'200':
description: success
schema:
$ref: '#/definitions/Company'
'400':
description: client doesn't exist
definitions:
Company:
description: ''
type: object
properties:
id:
type: string
description: Empty when creating a record
name:
type: string
description: Not empty when creating record, or updating this field
email:
type: string
I think the response body would be:
{
"code": 200,
"company": {...company object...}
}
Is this correct? or
{
"200": {...company object...}
}
Here is the document that swagger tool generated: