Swagger UI does not show file upload option (and not only that) in OpenAPI 3.0.3 Request Body info - swagger-ui

I was trying to add a file upload option for a POST request in Swagger UI by following the documentation.
The problem is this:
As you can see, Swagger UI does not render anything, neither for textual inputs nor for file inputs.
I tried to search on SO other answers about this but nothing.
This is the request body that I defined for the requestBody parameter of the path:
CreateTicketMessagePayload:
description: |-
Request multipart body required to proceed in the ticket message creation processes.
**Object part**:
```
{
"message": "Textual content of the message",
"private": "Flag that indicates the message is visible just for technicians"
}
```
**File part**:
"attachment": Message attachment file.
content:
multipart/form-data:
schema:
type: object
properties:
message:
type: string
example: This is a message
private:
type: boolean
example: false
attachment:
type: string
format: binary
What am I doing wrong?

In case of multipart/form-data requests, Swagger UI shows the inputs after you click "Try it out".
There's an existing enhancement request to display the inputs by default:
Display static documentation information for multipart properties in OpenAPI 3.0 files

Related

How to specify in OpenAPI adding a user to a group?

I am attempting to create a custom connector for MS Flow\Logic Apps that uses some of the REST endpoints that are part of the microsoft graph but am having trouble in understanding how to document the API in OpenAPI 2.0 specification
The MS documentation
https://learn.microsoft.com/en-us/graph/api/group-post-owners?view=graph-rest-1.0#example
says to include
"#odata.id": "https://graph.microsoft.com/v1.0/users/{id}"
as a $ref parameter as part of the request body
but how do I document this in OpenAPI 2.0 specification?
This is what I have got so far...
'/groups/{team-id}/owners':
post:
tags:
- teams.team
summary: Add a new owner to the team
operationId: teams.AddOwner
consumes:
- application/json
parameters:
- name: team-id
in: path
required: true
type: string
description: Id of the MS team
x-ms-summary: Team Id
x-ms-visibility: important
- name: body
in: body
required: true
schema:
type: object
properties:
userId:
type: string
description: Id of the user to be added as an owner to the team
x-ms-summary: User Id
x-ms-visibility: important
'#odata.id':
default: https://graph.microsoft.com/v1.0/users/{userId}
responses:
'204':
description: Success
default:
$ref: '#/responses/error'
x-ms-docs-operation-type: operation
When I submit the above to create the custom connector I get the following error
Specified file does not match OpenAPI 2.0 specification: 'JSON is valid against no schemas from 'oneOf'. Path 'paths./groups/{team-id}/owners.post.parameters[1]'.'
EDIT
I have updated the OpenAPI to look like below
This means that I can import and use this... but I have to construct the URL for the #odata.id parameter manually in the workflow!
"#odata.id": "https://graph.microsoft.com/v1.0/users/{id}"
'/groups/{team-id}/owners/$ref':
post:
tags:
- teams.team
summary: Add a new owner to the team
operationId: teams.AddOwner
consumes:
- application/json
parameters:
- name: team-id
in: path
required: true
type: string
description: Id of the MS team
x-ms-summary: Team Id
x-ms-visibility: important
- name: body
in: body
required: true
schema:
type: object
properties:
'#odata.id':
title: User Id
type: string
x-ms-summary: User Id
x-ms-visibility: important
responses:
'204':
description: Success
default:
$ref: '#/responses/error'
x-ms-docs-operation-type: operation
EDIT
How should I be specifying this to get the userId?
How do I specify the body parameter correctly?
Is there any documentation\examples on how to do this?
Any help would be much appreciated
Thanks in advance
Pete
One of the easiest ways I’ve found to create a PowerApps Custom Connector is to:
Use Postman to craft a working request
Build the Custom Connector from Blank
Test in the Custom Connector “Test” area
Then, you can download the Swagger file if you need it. Basically, let PowerApps build the Swagger file FOR YOU instead of the other way around.
Here is a YouTube video of the method I like to use.
https://m.youtube.com/watch?v=-wQljWG35zM

Swagger. How to define file download operation correctly

I use online Swagger Editor with OpenAPI 3.0 and I have to create a definition file download. I develop server-side and a customer should be able to create a client using YAML description without my "addition explanation". The relevant part of YAML is:
/files/download/{fileName}:
get:
summary: download file
operationId: downloadFile
description: this API is for file download
parameters:
- in: path
name: fileName
schema:
type: string
required: true
description: The name of file to download
responses:
200:
description: Operation performed successfully.
content:
application/octet-stream:
schema:
type: string
format: binary
...
The questions are:
Content. Currently, it is defined as octet-stream as a most common type, but actually, it depends on the type of a file from some predefined set of file types. Is there any way to define such kind of mapping (file type/content type) and use it with a content tag?
The response header should include a key/value pair attachment or inline and file name. The file name is defined in path - {fileName}. Is there any way to describe the concatenation of enum {attachment, inline} and the value of fileName?
I believe content is what you're looking for. You can also use contentReference to reference a reusable object in components.
For example:
paths:
/files/{fileName}:
get:
summary: download file
operationId: downloadFile
description: this API is for file download
parameters:
- in: path
name: fileName
schema:
type: string
required: true
description: The name of file to download
responses:
200:
description: Operation performed successfully.
content:
application/pdf:
schema:
type: string
format: binary
components:
contentTypes:
application/pdf:
schema:
type: string
format: binary

File upload on Swagger Editor OpenAPI 3 not showing the file browser when trying it out

I'm using Swagger Editor with OpenAPI 3.0. I need to document a route which consists of uploading an image. When attempting to "Try it out", I don't get the file browser to choose the image to upload in the request body, all I get is a JSON string with the name and type of parameter.
This is the YAML description of the route:
openapi: 3.0.0
...
paths:
/media/upload/thumbnail:
post:
tags:
- media
- publications
security:
- bearerAuth: []
summary: upload a kid's publication
operationId: uploadPublication
requestBody:
content:
multipart/form-data:
schema:
type: object
properties:
upload:
type: string
format: binary
responses:
'200':
description: Successful operation
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: ObjectId of the uploaded file in db (original size)
example: 5a6048b3fad06019afe44f24
filename:
type: string
example: myPainting.png
thumbnail:
type: string
description: ObjectId of the uploaded file in db (thumbnai size)
example: 5a6048b3fad06019afe44f26
'400':
description: Authentication failed
What am I missing here?
Your definition is correct.
Support for file upload for multipart/form-data requests in OpenAPI 3.0 definitions has been added in Swagger Editor 3.5.7 and Swagger UI 3.16.0. Make sure you are using a version that supports file upload.
For one of my same kind of concern !!!
I had to modify the input type to requested endpoint method.
Note- It might not address all type of requirements, but few can definitely be benefitted from this
Before:
/myEndpoint( #RequestBody RequestModelName requestModelName )
where RequestModelName has properties and getter/setter...
private MultipartFile file
private String otherProp
By this I could NOT see File option in swagger.
After:
/myEndpoint( #RequestParam MultipartFile file, #RequestParam String otherProp )
And then I could see File option in swagger...
Try with
content:
image/png:
schema:
properties:
file:
type: string
format: binary

SwaggerUI/YAML - should NOT have additional properties additionalProperty: requestBody

Designing an API using editor.swagger.io I find myself unable to add a requestBody attribute, getting an error I cannot address:
Schema error at paths['/projects/{projectId}/user'].post
should NOT have additional properties
additionalProperty: requestBody
Jump to line 91
I don't understand what I'm doing wrong, especially after looking at the requestBody documentation. Research has brought me nothing other than the tendency for errors to be misleading.
EDIT: From what the answers here have shown, it looks like the editor is supposed to use OpenAPI 2.0, but actually expects 3.0 while returning errors for both. I'd use some help on what to use, given that I've included a
swagger: "2.0"
line at the beginning of the document.
While testing with openapi: 3.0.0 as shown by #Mike in his answer, I just get more errors about allowed additional properties.
Here's what's generating the error, line 91 being post: .
/projects/{projectId}/user:
post:
tags:
- projects
summary: Modify project user.
operationId: modifyProjectUser
parameters:
- name: projectId
in: path
description: ID of the project
required: true
type: integer
format: int32
requestBody:
content:
application/json:
schema:
$ref: '#/definitions/User'
responses:
"200":
description: Successful operation
schema:
type: array
items:
$ref: "#/definitions/User"
security:
- api_key: []
I got clarifications from an external source, so here's what I've learned:
Specifying swagger: 2.0 also means that the OpenAPI Specification 2.0.0 is expected by the editor, whereas I thought it used OAS 3.
I'm still unsure about why in: body did not work in the first place but I've added quotes around "body", which made the error disappear. Then I tried removing the quotes and it worked fine.
The editor doesn't seem very reliable when it comes to error reporting.
This error message looked familiar. Try inserting a schema: underneath your parameter's required: line, then indent the type: and format: lines.
Since I have not yet set up my own SwaggerUI server. I took your code snippet and pasted it into SwaggerHub. Then I removed the $ref: lines just to further simplify the codebase. Here's a screenshot of the error-free result.
In my case since I was using openapi: 3.0.0. The schema $ref should be '#/components/schemas/{schemaname}' instead of '#/definitions/schemas/{schemaname}'

In Swagger, how to define an API that consumes a file along with a schema parameter?

I am trying to use Swagger to define an API that accepts an actual file and a schema object that describes the contents of a file. Here is a snippet of the Swagger YAML. However it won't validate in the Swagger Editor.
/document:
post:
summary: Api Summary
description: Api Description
consumes:
- multipart/form-data
parameters:
- name: documentDetails
in: formData
description: Document Details
required: true
schema:
$ref: '#/definitions/Document'
- name: document
in: formData
description: The actual document
required: true
type: file
The Swagger Editor throws the following validation error:
Swagger Error: Data does not match any schemas from 'oneOf'
Am I missing something? Or Is this not a supported feature of Swagger?
This is possible in OpenAPI 3.0, but not in OpenAPI/Swagger 2.0.
OpenAPI/Swagger 2.0 does not support objects in form data. Form parameters can be primitive values, arrays of primitives, and files, but not objects. So your example cannot be described using OpenAPI 2.0.
In OpenAPI 3.0, you can use:
paths:
/document:
post:
summary: Api Summary
description: Api Description
requestBody:
required: true
content:
multipart/form-data:
# Form parameters from 2.0 become body schema properties in 3.0
schema:
type: object
properties:
# Schema properties correspond to individual parts
# of the multipart request
document:
# In 3.0, files are binary strings
type: string
format: binary
description: The actual document
documentDetails:
$ref: '#/components/schemas/Document'
# The default Content-Type for objects is `application/json`
required:
- document
- documentDetails
Relevant parts of the 3.0 Specification:
Considerations for File Uploads
Special Considerations for multipart Content
swagger does not support type 'object' in formData, only as body parameters.
It is not possible using Swagger 2.0 , you can only read it as a type 'file' ,
https://swagger.io/docs/specification/2-0/file-upload/
On a related note please be aware that uploading array of files is also not supported in Swagger 2.0 but it is supported in Open API 3.0 .
https://github.com/OAI/OpenAPI-Specification/issues/254

Resources