How do I add a URL link to my swagger API, referencing localhost?. I dont want to add a hardcoded URL to the file, as the URL will differ on each enviornment. Trying the method below (specifying localhost) does not work.
externalDocs:
description: "View application metrics"
url: "http://localhost:3001/metrics"
You can follow the below steps:
Convert the yaml in json
Change the host and save it
Convert the saved json again to yaml
In swagger it takes json file for documentation so you might don't require the 3rd step.
const path = require("path");
const yaml = require("js-yaml");
const fs = require("fs");
const host = "127.0.0.1:3000"; // any host
const doc = yaml.safeLoad(fs.readFileSync("swagger.yaml"));
doc.host = host;
fs.writeFileSync(
path.join("swagger_new.json"),
JSON.stringify(doc, null, " ")
);
hope it helped!
Relative externalDocs URLs are supported in OpenAPI 3.0 (openapi: 3.0.0) but not in OpenAPI 2.0 (swagger: '2.0').
Assuming you use OpenAPI 3.0 and your OpenAPI file is hosted at http://localhost:3001/openapi.yaml, you can use:
openapi: 3.0.0
...
externalDocs:
description: View application metrics
url: /metrics # <--- http://localhost:3001/metrics
Note: If your API definition includes servers, relative URLs are resolved against servers rather than the location of the OpenAPI file.
openapi: 3.0.0
...
servers:
- url: 'https://api.example.com/v1'
externalDocs:
description: View application metrics
url: /metrics # <--- https://api.example.com/metrics
More info: API Host and Base Path
Related
We are using connexion to serve the swagger ui. We are using the openapi 3.0.0 specification. Here is a small part of our swagger.yml:
openapi: 3.0.0
servers:
- url: /
paths:
/resource:
...
/resource2:
...
in this case the ui is served at /ui. We are however using nginx to redirect all requests to /resource into this container. We would like swagger-ui to be served at /some-subdir/ui instead of at /ui, in order to be able to redirect the requests to the right container.
trial 1
openapi: 3.0.0
servers:
- url: /app
paths:
/resource:
...
/resource2:
...
which works, except that the resources are now served at /app/resource etc, while the same resource might in the future be served by another app, so we don't want the app name to appear in the URL of the resources (while it might be acceptable just for the swagger-ui).
trial 2
I found that, when constructing the connexion app, I could specify the swagger_url option:
options = {
'swagger_url': '/app/ui'
}
connexion_app = connexion.App(__name__, specification_dir='./', options=options)
now the swagger-ui is served at /app/ui, but the ui is trying to serve /openapi.json which is not reachable since not under /app (or any other subdir).
Almost there, there is another (well hidden) option to change the path to the openapi.json, the combination with swagger_url works:
options = {
'swagger_url': '/app/ui',
'openapi_spec_path': '/app/openapi.json'
}
connexion_app = connexion.App(__name__, specification_dir='./', options=options)
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
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.
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 URL like this:
/id/{idnumber}/status
In this URL, /id/{idnumber} is the API base path, and /status is the resource.
I know that OpenAPI (Swagger) allows parameters in paths, like so:
paths:
/id/{number}/status:
but this is not what I need, because /id/{idnumber} is the base path and not part of the resoruce path.
Is there any way to have a parameter in the base path?
host: my.api.com
basePath: /id/{idnumber} # <---
paths:
/status:
Parameterized base paths are supported in OpenAPI 3.x, using server variables:
openapi: 3.0.0
...
servers:
- url: https://my.api.com/id/{number}
variables:
number:
default: '-1'
Note that server variables MUST have a default value - it will be used if the client does not supply a value.
For details, see:
Server Object and Server Variable Object sections of the the OpenAPI 3.0 Specification
API Server and Base URL on swagger.io
I don't think basePath allows variables.
For your case, you don't need to use basePath. You can simply put /id/{idnumber} in the URL path. For example:
"/pet/{petId}": {