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}": {
Related
Got following issue using OpenAPI / Swagger with ESP 1.35.0 on Cloud Run:
/go/{ppage}/subitem:
get:
summary: Get a subitem
operationId: ppage
parameters:
- in: path
name: ppage
type: string
required: true
description: Get/Retrieve a subitem
x-google-backend:
address: https://example.com/go
Given an operation config above, path gets translated into https://example.com/go?ppage=m2jobs, where:
{ppage} path parameter becomes query parameter with key ppage in a call to the backend and
/subitem part of the path vanishes in a call to the backend
Is it correct/expected?
Please advise.
Indeed, according with the following link, the backend proto translates the path parameter to query parameter and the /path/ vanishes after the first /{path param}/
https://github.com/googleapis/googleapis/blob/master/google/api/backend.proto#L35-L91
Your assumptions are correct!
Best
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
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
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.