FAQ
The questions teams ask before they adopt API Genie, with the answer and where the reference says it. For a command that misbehaves, see Troubleshooting.
Does anything leave my machine?
No. The command-line tools open no connection unless a command names a server: nothing is sent
anywhere, and no telemetry file is written unless APIGENIE_TELEMETRY_FILE names one, in which
case each run writes a local log of the version, the commands, the time taken by internal steps
and the errors met, without usernames, API keys or the content of your files
(Telemetry).
apigenie lint,format,diff,bundleandconvertread files: remote$refURLs are not supported (bundle).apigenie-cataloglists the specifications of the repository and writes names and owners intoapigenie.yaml; the repository is the catalog, nothing is uploaded (apigenie-catalog).apigenie testandapigenie-server --proxy-tosend requests to the server you name, and to no one else (test, contract testing).- The editor opens a folder of your machine in the browser and writes back to it; its Try it out sends the requests you fire to the server of the document (hosts).
- The documentation site
apigenie-generator docswrites is built on your machine; itsnpm installfetches its dependencies from the npm registry (docs).
Which versions of the standards do the tools read?
| Standard | Read | Not read |
|---|---|---|
| OpenAPI | 3.0, 3.1 and 3.2 | |
| Swagger | 2.0 | the generators and the server take Swagger 2.0 after apigenie convert --to openapi32 |
| AsyncAPI | 3 | AsyncAPI 2 documents are rejected |
| Protobuf | proto3 | proto2 and editions files are rejected |
| GraphQL | schemas and operations |
The linter rules say per standard what each linter reads; the generators’ pages say which documents each target takes (apigenie-generator).
Does it replace Spectral?
For linting, yes: apigenie lint has built-in rulesets per standard, takes custom rules in
Spectral’s format (given, then, the core functions and JavaScript functions), disables a rule
in one place with x-apigenie-lint-disable, fixes what has a safe fix with --fix, and writes
the same report formats for CI. Migrate from Spectral maps
the rules of spectral:oas by name, moves the custom rules and functions over, and lists what
has no counterpart. Spectral has no formatter, differ, mock or generator, so nothing else moves.
Does it run on Windows?
Yes. Downloads has a zip for Windows x64 with the five executables, and
npm install -g @mykulyak/api-genie installs the same binaries wherever Node.js 18 or later
runs. The other builds are Linux x64 (an archive, a .deb and an .rpm) and macOS on Apple
silicon (also Homebrew, which serves Linux too). The Quickstart has
the commands for each channel.
Is there a Docker image?
Two, built for linux/amd64: mykulyak/apigenie with apigenie and apigenie-generator, and
mykulyak/apigenie-server with the mock. Both work in /mnt/data, where you mount the directory
of your files (Quickstart).
Does it work behind a proxy, or with a private certificate authority?
The commands that read files make no connection, so a proxy doesn’t matter to them. apigenie test
and apigenie-server --proxy-to connect to the server you name directly: the tools don’t read
HTTP_PROXY or HTTPS_PROXY. A private authority is given with --ca-cert (repeatable), a
client certificate with --client-cert and --client-key, and --insecure skips the
verification of the server’s certificate while the traffic stays encrypted
(test, server,
TLS). apigenie-server serves TLS itself with --tls-cert and
--tls-key.
What does it cost, and under which license?
The command-line tools are free (pricing). apigenie license prints the license
text, and apigenie license --list the open source libraries the tools are built with
(credits).
Can scripts and CI rely on the output?
From 1.0.0 the command names, the options, the configuration keys, the environment variables, the
exit statuses, the formatVersion of each JSON report, the admin API and the x-apigenie-*
extensions follow semantic versioning; the text of the messages, the wording of --help, the
inside of generated code and the experimental commands don’t. Versions below 1.0.0 make no such
promise, and the changelog lists what each one broke. The
compatibility promise says what is covered and how
deprecation works; read the JSON, SARIF, checkstyle, TAP or JUnit output in scripts, not the text
formatters.
Where do I ask a question or report a bug?
In an issue at github.com/mykulyak/api-genie/issues,
with the output of apigenie --version, the command line, and the document or a reduced one
that shows the behaviour. A break of something the compatibility promise covers is a bug, fixed
in a patch release.