API Genie

One section per symptom, with what the message means and what to change. The questions teams ask before a command runs are on the FAQ.

apigenie is not found after npm install -g

The directory npm installs global commands in isn’t on the PATH. npm prefix -g prints the prefix: the commands are in its bin directory on macOS and Linux, and in the prefix itself on Windows. Add it to the PATH and open a new terminal, or run the CLI without a global install with npx @mykulyak/api-genie --version. The other channels put the tools in a directory that is on the PATH already (Quickstart).

A command stops with “unknown property” or “Unsupported configuration version”

The configuration file is checked against its schema before any command reads it, whichever command runs and whichever section is wrong, and the command stops with exit status 2:

apigenie.yaml:4:12: /commands/lint/rulez: unknown property 'rulez'; did you mean 'rules'?

The message names the file, the line, the JSON pointer of the value and, for a misspelled key, the closest known name. version has to be the string '1.0': in YAML, version: 1.0 is a number. The file is found in the current directory or a parent up to the root of the repository, so a broken file higher up stops the commands below it; --no-config runs the command without any file to tell the two apart, and apigenie config check FILE checks a file without running anything. Where apigenie.yaml is found has the details.

A rule reports an issue in a document that is valid

A rule is a convention, not the specification: a valid document can still miss a description or name a tag twice. Each issue names its rule, and the rule’s page in the linter rules says what it checks and why. If the convention isn’t yours, change the rule’s severity or turn it off under commands.lint.rules; if it holds everywhere but one place, disable it there with x-apigenie-lint-disable on the object (disabling rules in a document):

version: '1.0'
commands:
  lint:
    rules:
      info-defined: off

If the rule is wrong about the document, open an issue with the document and the rule’s id.

The mock answers 404 or 405

The paths of the document are served under the path of its first server (/v1 for https://api.example.com/v1) and as they are. A 404 is a path the document doesn’t have, a 405 a method the path doesn’t declare, and the problem details name the method and the path the mock looked for. Check the servers of the document and --base-path, which replaces the prefix; with server.strict_base_path the paths are served only under it. The dashboard lists the routes the mock serves. How the mock picks a response walks through the routing and what follows.

The mock answers 422 to a request my client considers valid

The request is checked against its operation before an answer is chosen, and the problem details list what failed, such as path.id: expected type integer, found string. The client and the document disagree, which is what the check is for; if the document is wrong, fix it. To see the finding without refusing the request, set validation.request: log in the configuration: the request is answered and the finding goes into the X-Apigenie-Mock-Violations headers and the log. A format the document uses beyond the format registry is declared in openapi.custom_formats of the configuration, and validation.formats: false turns the format checks off (Validation and security).

The validating proxy reports violations the team disputes

Each violation names its check and its severity. A check can be re-rated or turned off in contract.severity; response.header.undefined is off unless you turn it on. By default the proxy reports and changes nothing, and --fail-on errors fails the run on errors only, not on warnings or notes. What the validating proxy checks explains the checks and the severities; the contract testing page lists them.

apigenie diff rates a deliberate change as breaking

The rating comes from the rules of the standard, and --report detailed shows the node type and the property that rated each change. To let a deliberate removal through, announce it first: mark the element deprecated: true with an x-sunset date and remove it after the date, which the recommended rules rate as non-breaking; in a Protobuf file, reserve the number of a removed field. To change a rating for good, set the rule’s severity under commands.diff.rules. Accepting a breaking change has the four ways, and the tables of the recommended rules.

Generated code doesn’t compile

The toolchain. Each target’s page names what the generated code needs: Java 17 and Maven for client java, Node.js 18 or later for client fetch, Python 3.10 or later with pydantic 2.11 or later for client python, .NET 8 for client csharp and server aspnet, Elixir 1.18 or later for the Elixir targets (apigenie-generator).
The version. The inside of generated code can change in a minor release, so a file generated by one version next to files generated by another can fail to compile. Regenerate everything with one version, and pin that version or commit the generated code (compatibility).
The document. A document that references other files is bundled first with apigenie bundle, and a Swagger 2.0 document converted with apigenie convert. Lint the document before generating: a clean contract gives cleaner code.
Still failing. Open an issue with the document, or a reduced one, the command line and the version: a document the generator accepts and then writes code that doesn’t compile is a bug.

apigenie test or the proxy can’t reach an HTTPS server

A certificate the system doesn’t trust is given with --ca-cert FILE (repeatable), and a server that asks for a client certificate gets it with --client-cert and --client-key; --insecure skips the verification of the server’s certificate, and the traffic stays encrypted. The tools connect directly and don’t read HTTP_PROXY or HTTPS_PROXY, so a server reachable only through a proxy isn’t reachable for them (test, TLS).