If the OpenAPI specifcation being processed by vacuum
contains external references, then vacuum
will need to know
how to handle them when resolving the specification.
Reference Types
References come in three forms:
- Local references
- Remote references
- Relative references
Local references
Local references are those that are local to the specification being processed. They look something like this:
$ref: '#/components/schemas/Error'
They are local in the sense that they are contained within the same document as the reference.
vaccum
knows how to handle these references out of the box, without needing any further configuration.
Remote references
Remote references are those that are hosted on a remote server, and are accessed via a URL. They look something like this:
$ref: 'https://api.quobix.com/openapi.yaml#/components/schemas/Error'
The first part (before the hash) is the full URL to the remote file. The second part (after the hash) is the JSON Pointer to the object being referenced.
This is the correct way to reference remote files, vacuum will support this out of the box, without needing any further configuration.
However, this is generally not the way that remote references are used in the wild.
Most of the time an OpenAPI specification assumes you have downloaded the entire set of files from the remote location, before you start processing the specification, which is not a good assumption to make.
The worst of the offenders out there that does this is Digital Ocean.
Relative references
Relative references can be those that are hosted on a remote server, or on the local file system. They can be either!
$ref: '../../../resources/openapi.yaml#/components/schemas/Error'
So how does vacuum know the difference?
It doesn’t!
For example, when parsing the Digital Ocean specification, there are references to relative files that are hosted on the remote server.
This isn’t very useful if the indexing engine tries to find those files on the local file system (which is what the specification is indicating) and it can’t.
Providing a BaseURL
To solve this problem, vacuum
allows you to provide a BaseURL
that will be used to resolve relative references.
This URL is used by the resolver to resolve relative references correctly if they do not exist on the local file system.
This is done using the -p
/ --base
flag.
In the Digital Ocean
example, the BaseURL
would be https://raw.githubusercontent.com/digitalocean/openapi/main/specification
For example
vacuum lint digitalocean.yaml -p \
https://raw.githubusercontent.com/digitalocean/openapi/main/specification
Providing a Base working directory
If files are available locally, then you can provide a base working directory that will be used to resolve relative references. This directory is used by the resolver to resolve relative references correctly if they do exist on the local file system.
The default is the current working directory, however it can be set to anything using the same -p
/ --base
flag.
The index will look in ../../specs/openapi
as a base for relative files.
Automatic mode
If you just want vacuum to figure out where to look for remote files, or local files then just use the -u
/ --remote
flag. It will attempt to locate files locally from the current working directory, or will look up remote references
from the remote location defined by the ref.
For example:
Certificate Authentication for HTTPS Requests
When working with remote references or rulesets that require certificate-based authentication (such as private servers or corporate environments), vacuum supports client certificate authentication and custom CA certificates.
Client Certificate Authentication
Use the --cert-file
and --key-file
flags to provide client certificates for HTTPS requests:
Custom CA Certificates
Use the --ca-file
flag to specify a custom CA certificate for validating server certificates:
Combined Usage
You can combine client certificates and custom CA certificates:
Environment Variables
Certificate paths can also be configured using environment variables:
export VACUUM_CERT_FILE=/path/to/client.crt
export VACUUM_KEY_FILE=/path/to/client.key
export VACUUM_CA_FILE=/path/to/ca.crt
vacuum lint spec.yaml
Insecure Mode
For testing purposes only, you can skip TLS certificate verification using the --insecure
flag:
Warning: The --insecure
flag disables certificate verification and should only be used in testing environments. This makes connections vulnerable to man-in-the-middle attacks.