I have one API yaml file contains 3 APIs and all of API need header parameters with same definition.
would i know whether OAS 3.0 supports define same header parameters in the component and use $ref
/service1:
/post:
post:
**parameters:
- in: header
name: X-partner**
/service2:
/post:
post:
**parameters:
- in: header
name: X-partner**
/service3:
/post:
post:
**parameters:
- in: header
name: X-partner**
how to define the X-partner in component so that I do not need to copy&paste every time? Thanks
Yes, you can define reusable header parameters (and other parameter types) in the global components/parameters section and reference them by using $ref.
openapi: 3.0.2
...
components:
parameters:
X-partner:
in: header
name: X-partner
schema:
type: string
required: true
paths:
/service1:
post:
parameters:
- $ref: '#/components/parameters/X-partner'
Related
In some documents it says it allows this:
parameters:
- name: body
'in': 'body'
required: true
schema:
type: string
But in reality, the in argument can only be path, query, cookie or header.
I also could not skip the parameters, because it would generate the wrong rust code.
Yes! As described in the docs, here (under 'Primitive Body'):
https://swagger.io/docs/specification/2-0/describing-request-body/
In your swagger.yml you can specify it like so:
paths:
/status:
post:
summary: Updates the status message.
consumes:
- text/plain # <----------
parameters:
- in: body
name: status
required: true
schema:
type: string # <----------
responses:
200:
description: Success!
This is the exact code snipped from the docs, pasted here for your convenience. :)
No I don't think there is any way you can make the request body object part of your parameter object anymore, but you could skip your parameters with:
parameters: []
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.
there is a url like
http://someservice.com/confirm?{token}
Is this any way how to describe this endpoint in terms of swagger notation
if use as query parameter then you get
/confirm:
get:
summary: ...
parameters:
- in: query
name: token
...
http://someservice.com/confirm?token=value that is not OK
from other side it is not possible to use url notation in follow way:
/confirm?{token}:
get:
summary: ...
parameters:
- in: path
name: token
...
due to query strings in paths are not allowed.
This is currently not supported, neither in OpenAPI 2.0 nor in OpenAPI 3.0. Here's the corresponding feature request:
Support for arbitrary query strings
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 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.