I am using OpenAPI3.0.2 in swagger and if I want to document my POST call with:
paths:
/<myPath>
post:
tags:
- <myTag>
summary: <mySummary>
description: <myDescription>
operationId: <myID>
requestBody:
description: <myDescription>
content:
application/x-www-form-urlencoded:
schema:
oneOf:
- $ref: '#/components/schemas/<schema1>'
- $ref: '#/components/schemas/<schema2>'
and schema:
components:
schemas:
<schema1>:
type: object
properties:
example1:
type: array
items:
type: string
pageSize:
type: integer
format: int64
page:
type: integer
format: int64
<schema2>:
type: object
properties:
example2:
type: array
items:
type: string
pageSize:
type: integer
format: int64
page:
type: integer
format: int64
My example value {example1:[test]} gets encoded to:
curl -X POST "http://localhost:8000/<myPath>" -H "accept: */*" -H "Content-Type: application/x-www-form-urlencoded" -d "0=%7B&1=e&2=x&3=a&4=m&5=p&6=l&7=e&8=1&9=%3A&10=%5B&11=t&12=e&13=s&14=t&15=%5D&16=%7D"
which results in this on the server-side:
<QueryDict: {'0': ['{'], '1': ['e'], '2': ['x'], '3': ['a'], '4': ['m'], '5': ['p'], '6': ['l'], '7': ['e'], '8': ['1'], '9': ['}']}>
instead of <QueryDict: {'example1': ['test']}>
I want to give information to the POST section of my request (which works with application/x-www-form-urlencoded). Because ultimately I want to read this out with request_source.getlist in my django server.
I already tried adding encoding information in the application/x-www-form-urlencoded like:
encoding:
payload:
contentType: application/json
but without success
Related
I have the following swagger spec for the endpoint:
records-by-time:
post:
operationId: idOfRecordsByTimeEndpoint
parameters:
- in: body
name: Body
schema:
$ref: '#/definitions/RecordsByTimeRequest'
responses:
"200":
$ref: '#/responses/RecordsByTimeResponse'
summary: 'Return records where fieldName value lies between #/definitions/RecordsByTimeRequest/left_bound and right_bound.'
tags:
- get-records
And I have the following definition
definitions:
RecordsByTimeRequest:
properties:
driver_name:
type: string
x-go-name: DriverName
field_name:
type: string
x-go-name: FieldName
left_bound:
format: date-time
type: string
x-go-name: LeftBound
right_bound:
format: date-time
type: string
x-go-name: RightBound
table_name:
type: string
x-go-name: TableName
Could I make left_bound in the summary references left_bound in the definition of the request, maybe a link to the field in the request definition field? If I can, how to apply it to go-swagger comments.
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 have the following API definition in SwaggerHub:
swagger: '2.0'
info:
description: defaultDescription
version: '0.1'
title: defaultTitle
host: swapi.co
paths:
/api/people:
get:
produces:
- application/json
parameters:
- name: search
in: query
required: false
type: string
x-example: luke
responses:
'200':
description: Definition generated from Swagger Inspector
schema:
$ref: '#/definitions/Model0'
responseSchema:
$ref: '#/definitions/Model0'
definitions:
Results:
properties:
name:
type: string
height:
type: string
mass:
type: string
hair_color:
type: string
skin_color:
type: string
eye_color:
type: string
birth_year:
type: string
gender:
type: string
homeworld:
type: string
films:
type: array
items:
type: string
species:
type: array
items:
type: string
vehicles:
type: array
items:
type: string
starships:
type: array
items:
type: string
created:
type: string
edited:
type: string
url:
type: string
Model0:
properties:
count:
type: integer
format: int32
next:
type: object
previous:
type: object
results:
type: array
items:
$ref: '#/definitions/Results'
I cannot make this basic GET command to bring back the data I'm seeking. It only returns this:
TypeError: Failed to fetch
I'm unsure if it's a syntax issue, or possibly spacing, but I'm also getting an error for line 19 that reads:
should NOT have additional properties
additionalProperty: responseSchema, description, schema
Any ideas what is wrong?
https://swapi.co seems to be HTTPS-only, so you need to add
schemes:
- https
to you API definition to specify the protocol for requests.
but I'm also getting an error for line 19 that reads: "should NOT have additional properties additionalProperty: responseSchema, description, schema".
Remove these lines:
responseSchema:
$ref: '#/definitions/Model0'
There's no responseSchema keyword in OpenAPI.
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:
Working on writing an API spec for my service with swagger. I'm using a model definition ('#/definitions/prototype') as the body parameter of both the POST /prototypes and PATCH /prototypes/:id routes.
How do you specify that the PATCH route only accepts a subset of the properties in the body of the request that the POST route does? For example, I want the PATCH /instances/:id route to only allow modification of the mobileDeviceId prototypes property.
swagger: "2.0"
info:
title: ""
description: ""
version: "1.0.0"
host: foo.example.com
schemes:
- https
basePath: /v1
produces:
- application/json
consumes:
- application/json
paths:
/prototypes:
post:
summary: Create new prototype
parameters:
- name: prototype
in: body
description: Prototype object
required: true
schema:
$ref: "#/definitions/Prototype"
responses:
201:
description: Success
schema:
$ref: "#/definitions/SuccessCreated"
403:
description: Prototype limit exceeded error
schema:
$ref: "#/definitions/Error"
default:
description: Unexpected error
schema:
$ref: "#/definitions/Error"
/prototypes/{id}:
patch:
summary: Update an existing prototype's properties
parameters:
- name: id
in: path
type: number
description: ID property of a prototype
required: true
- name: prototype
in: body
description: Prototype object
required: true
schema:
$ref: "#/definitions/Prototype"
responses:
200:
description: Success
definitions:
Prototype:
type: object
properties:
id:
type: integer
format: int64
name:
type: string
mobileDeviceId:
type: number
SuccessCreated:
type: object
description: Returned as response to successful resource create request
properties:
code:
type: number
default: 201
message:
type: string
Error:
type: object
properties:
code:
type: integer
format: int32
message:
type: string
fields:
type: string
Swagger uses json-schema: http://json-schema.org
$refs provide you w/ a way to repeat existing json-schema at a new path.
Notice that you are using a $ref for patch/parameters/-name:prototype/schema.
You can create a new definition just for patch in the definitions section and reference it instead
swagger: "2.0"
info:
title: ""
description: ""
version: "1.0.0"
host: foo.example.com
schemes:
- https
basePath: /v1
produces:
- application/json
consumes:
- application/json
paths:
/prototypes:
post:
summary: Create new prototype
parameters:
- name: prototype
in: body
description: Prototype object
required: true
schema:
$ref: "#/definitions/Prototype"
responses:
201:
description: Success
schema:
$ref: "#/definitions/SuccessCreated"
403:
description: Prototype limit exceeded error
schema:
$ref: "#/definitions/Error"
default:
description: Unexpected error
schema:
$ref: "#/definitions/Error"
/prototypes/{id}:
patch:
summary: Update an existing prototype's properties
parameters:
- name: id
in: path
type: number
description: ID property of a prototype
required: true
- name: prototype
in: body
description: Prototype object
required: true
schema:
$ref: "#/definitions/PatchPrototype"
responses:
200:
description: Success
definitions:
Prototype:
type: object
properties:
id:
type: integer
format: int64
name:
type: string
mobileDeviceId:
type: number
PatchPrototype:
type: object
properties:
mobileDeviceId:
type: number
SuccessCreated:
type: object
description: Returned as response to successful resource create request
properties:
code:
type: number
default: 201
message:
type: string
Error:
type: object
properties:
code:
type: integer
format: int32
message:
type: string
fields:
type: string