CLI

Check the contract before it merges

apigenie lints, formats, compares and contract-tests API descriptions, locally and in CI: one binary, one exit status table.

Lint your first fileRead the reference

From the edit to the merge

The same binary runs while you edit, before the commit and in the pull request, where its exit status decides whether the branch merges.

apigenie runs while you edit, before the commit and in the pull request; status 1 in the pull request stops it, status 0 lets it merge One binary, three placesEditapigenie lint --watchapigenie lint --fixCommitapigenie formatPull requestapigenie lintapigenie format --checkapigenie diff main.yamlGitHub Action: annotationsstatus 0status 1Mergeevery check exited 0It stops here
Lint errors, unformatted files and breaking changes exit with 1. Warnings alone exit with 0 and merge.

Lint errors and breaking changes, caught

Lint errors, formatting differences and breaking changes return status 1; lint warnings alone do not. Lint and diff also produce JSON reports with --formatter json. The GitHub Action runs these checks in pull requests.

$ apigenie lint orders.yaml
  45:9   warning  Parameter should be named order_id                                parameter-naming
  53:7   error    Operation has no meaningful description                           operation-description-defined
  97:11  warning  String schema does not define constraints restricting its length  schema-constraints

  3 issues (1 errors, 2 warnings)
$ apigenie format --check orders.yaml
orders.yaml
1 file(s) would be reformatted.
$ git show main:orders.yaml > main.yaml
$ apigenie diff main.yaml orders.yaml
orders.yaml
  53  7  breaking  Modified operation GET /orders/{orderId}
  53  7  breaking  Removed parameter expand in query
$ echo $?
1

What it does

  • lintChecks API descriptions against built-in and Spectral-style rulesets, with safe fixes through --fix. Reports include SARIF, JUnit, checkstyle and JSON.
  • formatPuts every file in your team's style: indentation, key order, YAML styles. --check fails the build on unformatted files.
  • diffCompares two versions of an API, rates every change as breaking, non-breaking or non-functional, and fails on the breaking ones.
  • changelogBuilds the changelog of an API from its Git history, per commit or per release tag.
  • testRuns .http files, or requests generated from the contract, against a live API and checks every exchange against the contract.
  • bundle, convert, overlayBundles a multi-file API into one file, converts Swagger 2.0 to OpenAPI 3.2 and WSDL to OpenAPI 3.1 (experimental), and applies OpenAPI Overlays.
  • i18nExtracts the texts of an API for translation, checks that a translation is complete, and writes the translated API.
  • evolvePlans a breaking change in expand and contract stages for you to review before rollout (experimental).
  • configOne apigenie.yaml for every command, checked against its JSON Schema, with completion in your editor.

Install

With Homebrew on macOS and Linux, or with npm anywhere Node.js runs. Both install the four binaries, as do the .deb and .rpm packages and the archives on the downloads page. Docker has two images: mykulyak/apigenie with the CLI and the generator, and mykulyak/apigenie-server.

brew install mykulyak/apigenie/apigenie
npm install -g @mykulyak/api-genie

Installed next to it

The packages install four executables of the same version.

  • Generatorapigenie-generator: clients, servers, documentation and test data from the same files.
  • Serverapigenie-server: mocks, and a validating proxy in front of a real API.
  • Catalogapigenie-catalog: the API specifications of a repository, with their owners.

Use cases

Lint your first fileRead the reference