In Flasgger, I'm trying to create documentation for route which accepts uploaded files. However, despite sticking to the specification, I cannot display file selector in Flasgger UI.
I'm using latest (as of today) flasgger==0.9.1 running OpenAPI 3 specs (as in "openapi": '3.0.0') and I saw this commit in Swagger-UI, that enables file selectors for POST file requests.
I know similar questions were asked before, but none of them related to OAS version 3.
My code snippet is below:
Upload a file
Returns ID of uploaded file
---
tags:
- name: "attachments"
schemes:
- "http"
consumes:
- application/octet-stream
produces:
- application/json
requestBody:
content:
application/octet-stream:
schema:
type: file
format: binary
responses:
200:
... etc
And I get just an empty block input in Flasgger UI. Is it possible Flasgger does not support it even though Swagger-UI does (I thought it's built on top of it)? Or the syntax is wrong?
You are mixing OpenAPI 2.0 and 3.0 syntax. In OAS3, files are described as binary strings, that is type: string and not type: file. Also, the consumes, produces and schemes keywords are not used in OAS3.
Try the following:
Upload a file
Returns ID of uploaded file
---
tags:
- attachments
requestBody:
content:
application/octet-stream:
schema:
type: string # <-------
format: binary
responses:
'200':
description: OK
content:
application/json:
schema:
# ... etc
Note that OAS3 file upload requires Swager UI 3.16.0+ but Flassger 0.9.1 is bundled with UI 3.14.2 and there seems to be no way to update the bundled Swagger UI. This possibility will be added in the next update, Flassger 0.9.2:
https://github.com/rochacbruno/flasgger#externally-loading-swagger-ui-and-jquery-jscss
So you'll need to wait for Flassger 0.9.2.
I also recommend that you check the generated OpenAPI file for syntax errors using the Swagger Editor, because syntax errors might cause incorrect parsing/rendering. This answer explains how to export your OpenAPI file from Swagger UI so that you can use it elsewhere.
Related
I am facing fellow two problems related to Swagger open API
I am not able to pass custom header through swagger open API while calling my API, please suggest how can we pass custom header, through swagger open API.
When I added POI dependency on my project's pom.xml, it stopped working through swagger open API, however, it is working with the postman, please suggest what could be the issue.
From Describing Parameters:
An API call may require that custom headers be sent with an HTTP request. OpenAPI lets you define custom request headers as in: header parameters. For example, suppose, a call to GET /ping requires the X-Request-ID header:
GET /ping HTTP/1.1
Host: example.com
X-Request-ID: 77e1c83b-7bb0-437b-bc50-a7a58e5660ac
Using OpenAPI 3.0, you would define this operation as follows:
paths:
/ping:
get:
summary: Checks if the server is alive
parameters:
- in: header
name: X-Request-ID
schema:
type: string
format: uuid
required: true
I'm working on documenting our existing API's in swagger using open api 3.0.0 specification. I would like to understand the procedure on documenting the contents of a file that is to be uploaded. For e.g.
Say the file that is to be uploaded is response.json, and it has the following content:
{
name: xyz,
age: 50
}
I would like to know the procedure for documenting the above JSON so that clients using our API should provide the file in the aforesaid JSON format.
I'm introducing an optional "query parameter" (with default value) for one of my API endpoint ( i.e. /foo2) but hoping that existing API consumers don't have to make any changes in their application when they regenerate the java client stub from the new swagger file.
I was expecting that the generated java client will offer overloaded methods, to operate with and without a method parameter, so that my existing API consumers can work without any changes to their call. At the same time, they can switch to its more generic offering.
public void foo2Get() throws ApiException {
public void foo2Get(String type) throws ApiException {
But it generates ONLY the latter. I don't see the former.
At the same time, generated python client from same swagger throws a var arg and this way it more flexible and hence old and new offerings will work without any issues.
def foo2_get(self, **kwargs):
(swagger sample used: attached)
** Description**
Is there a way to overcome this limitation with java code generator.
swagger-generator version
swagger 2.0
Swagger declaration file content or url
swagger: '2.0'
info:
title: identity
version: Unknown
consumes:
- application/json
produces:
- application/json
parameters:
typeParam:
name: type
in: query
required: false
allowEmptyValue: true
default: basic
type: string
enum:
- basic
- advanced
paths:
/foo2:
get:
consumes:
- application/json
parameters:
- "$ref": "#/parameters/typeParam"
responses:
'200':
description: OK
I have an API which allows any arbitrary path to be passed in, for example all of these:
/api/tags
/api/tags/foo
/api/tags/foo/bar/baz
Are valid paths. I tried to describe it as follows:
/tags{tag_path}:
get:
parameters:
- name: tag_path
in: path
required: true
type: string
default: "/"
However, https://generator.swagger.io encodes slashes in the path, so it doesn't work. So is there a way to describe my API in Swagger?
This is not supported as of OpenAPI 3.1, and I have to resort to a workaround.
If I have a path /tags{tag_path} and I enter something like this as tag_path: /foo/bar, then the actual query request URL will be: /tags%2Ffoo%2Fbar. So, I just added support for that on my backend: the endpoint handler for /tags* urldecodes the path (which is %2Ffoo%2Fbar), and it becomes /foo/bar again.
Yes, a hack, but it works, and it's better than nothing. In my case, tag names can't contain the / character, so there's no conflict. Your mileage may vary, of course.
If you are using a framework like Connexion, chances are it does support a wildcard path parameter (even though it is not in the OpenAPI spec).
Here is an example for Connexion.
paths:
/pages/{path}:
get:
# (...)
parameters:
- name: "path"
in: path
description: "Remainder of path, including slashes."
schema:
type: string
format: path
The difference is the format: path added.
I have the following yaml
/orgs:
post:
produces: ['application/json']
consumes: ['application/json']
parameters:
- in: query
name: newKey
type: boolean
- in: body
name: org
required: true
schema:
$ref: '#/definitions/Org'
responses:
201:
schema:
$ref: '#/definitions/Org'
In the "Try This" form in the editor, the preview of the POST looks correct (the JSON is in the post body, and the content-type is correct):
[
But when I hit the "Send Request" button, it seems to throw the JSON in as a url-encoded string and not send the body.
I cloned the swagger-editor today, built it and put it in my server to host it locally and try out the API I am building.
Why is it sending the body as a url-encoded string?
For that specific path and request method you have to set Content-Type = "multipart/form-data"
This ended up being an issue in swagger editor that was resolved in a github issue. I realize it's frowned upon to post links to solutions, but I'm not going to copy the whole thread here.