open api 3 posting an array of files - swagger

I am using swagger hub to create this API; but it doesn't support multi files in the UI so I am unsure if I am doing this right
My goal is to have the following
item:{Json describe the item}
images[] = images for item posted as an array
titles[] = Parallel array to images that has the title for image
alt_texts[] = Parallel array to images that has the alt text for image
This has to be multipart since it is files; but am unsure if I setup the structure correctly.
Swagger/Open API Code
post:
summary: Add a new item to the store
description: ''
operationId: addItem
requestBody:
content:
multipart/form-data:
schema:
$ref: '#/components/schemas/NewItemWithImage'
description: Item object that needs to be added to the store
required: true
NewItemWithImage:
type: object
properties:
item:
$ref: '#/components/schemas/NewItem'
images[]:
type: array
items:
type: string
format: binary
titles[]:
type: array
items:
type: string
alt_texts[]:
type: array
items:
type: string
variation_ids[]:
type: array
items:
type: string
required:
- item

According to File Upload section in OpenAPI 3 specification:
File Upload
Files use a type: string schema with format: binary or format: base64,
depending on how the file contents will be encoded.
Multiple File Upload
Use the
multipart media type to define uploading an arbitrary number of files
(an array of files):
requestBody:
content:
multipart/form-data:
schema:
type: object
properties:
filename:
type: array
items:
type: string
format: binary
You current definition corresponds to the specification precisely:
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/NewItemWithImageUrl'
multipart/form-data:
schema:
$ref: '#/components/schemas/NewItemWithImage'
NewItemWithImage:
type: object
properties:
item:
$ref: '#/components/schemas/NewItem'
images[]:
type: array
items:
type: string
format: binary
titles[]:
type: array
items:
type: string
...

The code for swagger-ui is failing as of today in curlify.js
if (v instanceof win.File) {
curlified.push( `"${k}=#${v.name}${v.type ? `;type=${v.type}` : ""}"` )
} else {
curlified.push( `"${k}=${v}"` )
}
curlify.js is not taking the array into account and is sending:
curl -X POST "http://localhost:9122/upload-all" -H "accept: */*" -H "Content-Type: multipart/form-data" -F "my-attachment=[object File],[object File]"
and not something like:
curl -X POST "https://foo/v1/api/upload/" -H "accept: application/json" -H "Content-Type: multipart/form-data" -F "myfile=#bla;type=application/zip" -F "myfile=#foo;type=application/zip"

Related

How to hide swagger ref attributes in specific paths?

I have this structure in swagger documentation:
FunctionTitle:
type: object
required:
- funcId
- czechName
- priority
properties:
funcId:
type: number
format: id
example: 1226
czechName:
type: string
example: Guvernér
priority:
type: number
example: 21
org:
$ref: '#/definitions/Organ'
funcType:
$ref: '#/definitions/FunctionType'
In some path I want to return this structure, but without properties org and funcType. So my response should be something like that:
{
"funcId" : 1226,
"czechName" : "Guvernér",
priority: 21
}
I didnt find how to choose not to return properties org and funcType. I know I can create another model for it, but it will be better for me to only hide properties as I want and not to create another model. Here is example of my path:
/periods:
get:
tags:
- developers & users
summary: Periods
operationId: periods
description: |
By passing in the appropriate options, you can search for
available inventory in the system
produces:
- application/json
responses:
200:
description: search matching criteria
schema:
type: object
properties:
periods:
type: array
items:
$ref: '#/definitions/FunctionTitle'
400:
description: bad input parameter
Thank you for your answers!

swagger-ui - open api 3, multipart/form-data array problem

I'm uising swagger-ui with OpenApi 3.0.2 spec.
I set a requestBody with multipart/form-data content.
Everithing works fine when I execute the request from swagger-ui but...
If I add a parameter of type array, it will be transformed in curl call in this way:
-F "tags=my,tag"
I need the array to be exploded
-F 'tags[]=my' \
-F 'tags[]=tag'
I look at the documentation and find some style and explode properties, but they only works on parameters attribute, not on requestBody (?).
In my route file:
post:
tags:
- media-image
summary: Create a media image
requestBody:
description: A JSON object containing media image information
required: true
content:
multipart/form-data:
schema:
allOf:
- $ref: '../schemas/media-image-fillable.yaml'
- required:
- title
- back_office_title
- alt
- file
The media-image-fillable.yaml
type: object
allOf:
- $ref: './media-image-base.yaml'
- properties:
file:
type: string
format: binary
tags:
type: array
items:
type: string
and the media-image-base.yaml
type: object
properties:
title:
type: string
back_office_title:
type: string
description:
type: string
alt:
type: string
Ok, I found the solution.
I only had to rename tags property in tags[], now it works.

How to display object properties as separate fields in Swagger UI?

I am writing API documentation using OpenAPI 3.0. At the moment I have:
paths:
/script/update:
post:
tags:
- "Script"
summary: Update a script
operationId: updateScript
responses:
'200':
description: OK
"404":
description: Not Found
requestBody:
description: A script object in order to make the request
required: true
content:
application/x-www-form-urlencoded:
schema:
type: object
properties:
subsite_id:
type: string
script:
type: object
properties:
script:
$ref: '#/components/schemas/ScriptType'
type:
type: string
enum:
- custom
- interface
- freshbot
- feeder
- getter
- smcf
status:
$ref: '#/components/schemas/ScriptStatus'
comment:
type: string
format: string
reason:
type: string
format: string
To problem comes when I try to use to Swagger UI.
The only thing that appears is the following:
What I want is that the script object can be filled out field by field for each of the properties it has, like the subsite_id. What am I missing?
Swagger UI 3.x and 4.x do not have a form editor for JSON objects, so all JSON data needs to be entered in the JSON format: { "prop": value, ... }
Here's the corresponding feature request you can track:
https://github.com/swagger-api/swagger-ui/issues/2771

How to describe dynamic form data using OpenAPI (Swagger)?

I'm trying to create an OpenAPI definition for this multipart/form-data request:
curl -X POST \
http://localhost:1234/api/v1/Submit \
-H 'cache-control: no-cache' \
-H 'content-type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW' \
-H 'sessionkey: kjYgfORsZ0GeiCls0FcR7w==' \
-F item1=abc \
-F item2=def
-F item3=ghi
...
My API definition is like this:
post:
consumes:
- multipart/form-data
produces:
- application/json
parameters:
- in: formData
name: item1
type: string
- in: formData
name: item2
type: string
It works fine with fixed fields in formData.
However, my form data will be dynamic, and I need to be able to send arbitrary keys and values.
I tried changing form parameters to use an array and additionalProperties, but it does not produce the desired result:
- in: formData
schema:
additionalProperties:
type: object
...
- in: formData
type: array
items:
type: string
Is it possible to define dynamic formData with different keys and values?
Dynamic form data can be defined using OpenAPI 3.0 but not OpenAPI 2.0 (Swagger 2.0). OpenAPI 2.0 only supports fixed key names in form data.
In OpenAPI 3.0, you can describe dynamic form data using a schema with additionalProperties:
openapi: 3.0.2
...
servers:
- url: 'http://localhost:1234/api/v1'
paths:
/Submit:
post:
requestBody:
required: true
content:
multipart/form-data:
schema:
# Object properties correspond to form fields
type: object
additionalProperties:
type: string
responses:
'200':
description: OK
When testing the request in Swagger UI, enter the fields names and values in the JSON format:
{
"field1": "value1",
"field2": "value2",
"field3": "value3"
}
Swagger UI will send these values as individual form fields:

How to define different body parameters for same path in OpenAPI (Swagger)?

I have a service that can have two different kind of body parameters based on the Content-Type header.
E.g. for path /Pet:
If Content-Type: application/somecustom.resource+json is used, then POST can take up Pet as the body parameter.
If Content-Type: application/somecustom.function+json is used, then POST should take up some different body parameter to invoke a function and return a different response.
Any suggestion on how to manifest this in OpenAPI (Swagger)?
OpenAPI 3.0 supports different schemas per media type.
openapi: 3.0.0
...
paths:
/pet:
post:
requestBody:
required: true
content:
application/somecustom.resource+json:
schema:
$ref: '#/components/schemas/Pet'
application/somecustom.function+json:
schema:
$ref: '#/components/schemas/Foo'
No, it's not possible to define a two different body parameters for the same operation, in the same path item. The path item name are unique by virtue of being property names (and therefore "keys" in the JSON key-value map), and Swagger specification allows at most one body parameter in a given operation.
There are a few alternative approaches to address this need:
Create two separate path items
For example:
/pets/createFromDescription:
post:
summary: Create a pet from a basic description
operationId: createPetFromDescription
parameters:
- name: petDescription
in: body
required: true
schema:
$ref: "#/definitions/PetDescriptionObject"
responses:
200:
description: OK
/pets/createFromCatalog:
post:
summary: Create a pet from a standard catalog entry
operationId: createPetFromCatalogEntry
parameters:
- name: petCatalogEntry
in: body
required: true
schema:
$ref: "#/definitions/PetCatalogEntry"
responses:
200:
description: OK
Create subtypes, with a discriminator
Described in the Swagger–OpenAPI 2.0 specification here.
Example:
/pets:
post:
summary: Create a pet
operationId: createPet
parameters:
- name: petSource
in: body
description: Structured pet information, from which to create the object
required: true
schema:
$ref: "#/definitions/CreatePet_Request"
responses:
200:
description: OK
definitions:
CreatePet_Request:
type: object
properties:
requestVariant:
type: string
required:
- requestVariant
discriminator: requestVariant
PetDescriptionObject:
allOf:
- $ref: "#/definitions/CreatePet_Request"
- type: object
properties:
name:
type: string
description:
type: string
PetCatalogEntry:
allOf:
- $ref: "#/definitions/CreatePet_Request"
- type: object
properties:
SKU:
type: string
Breed:
type: string
Comments:
type: string
Neither of these methods is keyed to the media type of the request. While your request may accept multiple media types, if the use of a particular media type implies some requirement about the request body, you'd have to document that in the description property of the operation or body parameter.

Resources