Why API Genie

One install instead of a tool per job

Your repository lints with Spectral, mocks with Prism and generates a client with OpenAPI Generator: three tools, three versions to pin, Node.js and Java on the runner. API Genie does the three jobs, and the breaking-change check, from one install.The facts about the other tools are those of the migration guides, for Spectral 6.17, Redocly CLI 2.72, oasdiff 1.35, OpenAPI Generator 7.x, Prism 5.x and Buf 1.75, checked on 9 November 2026. The times are those of the linter performance page, for Spectral 6.17.1 and vacuum 0.39.3, measured on 8 November 2026. The transcript is from API Genie 0.12.0.

Install the CLIMove from the tool you have
  • No Node.js or Java on the runnerapigenie, apigenie-generator, apigenie-server, apigenie-catalog and apigenie-mcp are native executables for macOS on Apple silicon, Linux x64 and Windows x64. Homebrew, a .deb, an .rpm or an archive installs them without Node.js or Java; the Linux binary is statically linked. Spectral runs on Node.js, OpenAPI Generator on Java 11 or later. The npm package needs Node.js 18 or later and starts the same binaries.
  • One run for the REST API and its eventsapigenie lint reads OpenAPI 3.0 to 3.2, Swagger 2.0, AsyncAPI 3, proto3 and GraphQL, with a ruleset per standard in one apigenie.yaml. In the transcript below, one run lints the OpenAPI file and the AsyncAPI file of one API, and apigenie-server serves both.
  • Nothing leaves your machineThe 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. apigenie test and apigenie-server --proxy-to send requests to the server you name, and to no one else.

Lint, diff, mock and generate, from one install

orders.yaml describes an orders API in OpenAPI 3.1, order-events.yaml the events it sends in AsyncAPI 3.0, and main.yaml is the version of orders.yaml on the main branch. One apigenie.yaml, with extends: [recommended] and one rule turned off, applies to both files. apigenie lint exits with 1 on the error, apigenie diff on the breaking change, and apigenie diff --report status --formatter json main.yaml orders.yaml gives a script the same verdict: { "formatVersion": 1, "status": "breaking" }.

$ apigenie lint orders.yaml order-events.yaml
/home/me/shop/orders.yaml
   48:7  error    Operation has no meaningful description  operation-description-defined
   70:9  warning  Parameter should be named order_id       parameter-naming
  109:7  warning  Schema has no example                    schema-example-defined

  3 issues (1 errors, 2 warnings)

/home/me/shop/order-events.yaml
  20:9   warning  Parameter should be named order_id                  parameter-naming
  32:9   warning  Tag 'orders' has no meaningful description defined  tag-description-defined
  72:11  warning  Property name shippedAt should end with _at         schema-datetime-suffix

  3 issues (0 errors, 3 warnings)

$ apigenie diff main.yaml orders.yaml
orders.yaml
  79  7  breaking  Modified operation GET /orders/{orderId}
  79  7  breaking  Removed parameter expand in query
$ echo $?
1
$ apigenie-generator client fetch orders.yaml -o client --package-name orders-client
$ ls -m client/src
index.ts, metadata.ts, operations.ts, runtime.ts, types.ts
$ apigenie-server orders.yaml order-events.yaml
Listening on http://127.0.0.1:4010 (2 services)
  orders        http://127.0.0.1:4010/orders/v1 (spec: orders.yaml, 3 operations)
  order-events  http://127.0.0.1:4010/order-events (spec: order-events.yaml, 1 channel)
Admin API: http://127.0.0.1:4010/__apigenie
Dashboard: http://127.0.0.1:4010/__apigenie/ui

The tool you run today, and what carries over

Each row links its migration guide, which has the rest. The facts about the other tool are at the version the guide names.

JobTodayWith API GenieWhat carries over
Lint OpenAPI and AsyncAPISpectral 6.17apigenie lintThe rules in given and then with the core functions, your JavaScript functions, and the spectral:oas rules mapped by name. You copy a ruleset extended from a URL or an npm package into the repository. Migrate from Spectral
Lint and bundle OpenAPIRedocly CLI 2.72apigenie lint, apigenie bundleThe recommended rules by name, the decorators as OpenAPI Overlays, and, since 0.13.0, .redocly.lint-ignore.yaml as .apigenie.lint-ignore.yaml. Migrate from Redocly CLI
Breaking changesoasdiff 1.35apigenie diffThe x-sunset dates, which decide when a removal stops being breaking, and the checks as rules you re-tune; --deprecation-days-stable has no counterpart. The exit status is 1 on a breaking change, with no --fail-on. Migrate from oasdiff
Clients and serversOpenAPI Generator 7.xapigenie-generator client, apigenie-generator serverYour implementation files, written only when missing; .openapi-generator-ignore for the Spring, Java and FastAPI targets; a Spring or FastAPI project regenerated in place. Migrate from OpenAPI Generator
Mock and validation proxyPrism 5.xapigenie-serverThe address http://127.0.0.1:4010, Prefer: code=, example= and dynamic=, the 422 with problem details, and the proxy as a second mode of the same command. Migrate from Prism
Lint, diff and format ProtobufBuf 1.75apigenie lint, apigenie diff, apigenie formatThe lint rules by name and the buf.yaml settings, as sections of apigenie.yaml; buf generate stays. Migrate from Buf

Faster than Spectral and vacuum on the same rules

Median wall time in seconds for the 26 rules of spectral:oas that the three linters implement natively, on an Apple M1, measured on 8 November 2026 with Spectral 6.17.1, vacuum 0.39.3 and apigenie lint built from source after 0.12.0.

DocumentSpectralvacuumapigenie lint
small, 52 KiB0.7270.0500.023
medium, 282 KiB0.7950.1180.028
large, 8.2 MiB3.8971.9930.149

On the large document, the GitHub REST API, apigenie lint also checks the 243 webhooks under x-webhooks, which Spectral and vacuum skip, so the three report different counts. With 10 custom rules as JavaScript functions on the same document, it takes 2.234 s against Spectral's 3.820 s and vacuum's 5.203 s. Peak memory on the large document: 87 to 115 MiB for apigenie lint, 570 to 1,860 MiB for Spectral, 1.3 to 2.2 GiB for vacuum. Linter performance has the times with all four rulesets and the issue counts. It also gives the command lines to time the three linters on your own documents, with their default rules or your Spectral ruleset.

Adopt it one check at a time

  • Start with no configurationapigenie lint openapi.yaml runs the recommended ruleset of the file's standard. apigenie init writes an apigenie.yaml for the API descriptions it finds in the repository, and keeps the files that are there.
  • Keep the old tool until the reports agreeEvery migration guide starts with both tools installed, runs them on the same file, and removes the old one in its last step. apigenie lint and apigenie diff run beside Buf when your code comes from buf generate.
  • Your rules and your files carry overSpectral rules in given and then go under commands.lint.rules as they are, apart from the few keys the guide lists, such as aliases and overrides. A JavaScript function moves unchanged unless it reads a file, fetches a URL or sets a timer. The generator writes your implementation files only when they are missing, and reads .openapi-generator-ignore for Spring, Java and FastAPI.

One exit status table, for CI and for agents

  • The same exit status in every pipeline0 on success, 1 on findings: lint errors, breaking changes, format --check differences. 2 on a usage or input error. The same table for the five executables. From 1.0.0 the commands, the options, the exit statuses and the JSON outputs follow semantic versioning; apigenie-mcp and the experimental commands stay outside that promise.
  • Reports your CI already reads--formatter sarif for code scanning, JUnit, checkstyle, TAP and JSON with a formatVersion. The GitHub Action shows the issues as annotations on the pull request's files; the CI pages set up the same lint, format and breaking-change checks for GitLab, Azure Pipelines, Bitbucket Pipelines, CircleCI and Jenkins.
  • Agents run the same commandsapigenie-mcp (experimental) serves the lint, breaking-change, changelog and format checks to coding agents over MCP, apigenie init adds to AGENTS.md the section that tells them how to run the checks, and every page of Docs has a Markdown twin listed in llms.txt.

Where another tool is the better pick

What API Genie does not do, tool by tool, each card with the page that says it in full.

  • Spectral, for a shared ruleset served from npm or a URLapigenie lint reads ruleset files from the disk only. You copy a ruleset your repositories extend from a URL or an npm package into each of them. spectral:oas and spectral:asyncapi themselves don't load; recommended has the counterparts of about two thirds of spectral:oas.
  • Redocly CLI, for its platformpush, project, preview, login and eject work with the Redocly platform, and split, join, stats, score and respect have no counterpart. apigenie-generator docs replaces build-docs with a static site you host yourself.
  • oasdiff, for every difference as dataoasdiff diff prints every difference as YAML or JSON without a severity, --composed compares two sets of files as one API, and --lang translates the messages. apigenie diff --report detailed --formatter json is the nearest, in English, one pair of files at a time.
  • OpenAPI Generator, for Kotlin, Dart, PHP, Ruby or Scalaapigenie-generator writes 8 clients and 11 servers from OpenAPI, 6 of them experimental; OpenAPI Generator has 172 generators, Kotlin, Dart, PHP, Ruby and Scala clients among them, and templates to change the output. API Genie changes the output through options, an overlay and the x-apigenie extensions, with no templates.
  • Prism, for callbacksPrism sends the callback requests an operation declares; apigenie-server does not mock callbacks, webhooks or links. Prism also serves a Postman collection as the document, which apigenie-server does not.
  • Buf, for proto2, editions and code generationapigenie lint, diff and format read proto3 files only. buf generate with its plugins and the Buf Schema Registry have no counterpart: from .proto files, apigenie-generator writes code in Elixir only, a gRPC client and a gRPC server. Keep Buf for them, and run apigenie lint and apigenie diff beside it.
  • A reference your framework already servesThe doc components go into a page of yours, and apigenie-generator docs builds a static site with npm. If the Swagger UI page your application serves is all your readers need, keep it; the site adds the events, the GraphQL and Protobuf services, search and Try it out.
  • Postman, Insomnia or Bruno, for a collection of saved requestsThe editor's Try it out sends a request from the operation's preview, but no API Genie app holds a collection of saved requests: yours go in .http files in the repository, which apigenie test runs, with the ones it generates from the document, against a live server, and with --spec checks every request and response against the contract. apigenie test import turns a Postman collection into .http files.
  • The AsyncAPI 2 tooling you haveThe CLI reads AsyncAPI 3 and rejects AsyncAPI 2 documents. The editor imports an AsyncAPI 2.x document and shows the conversion as a diff; until the repository has moved to AsyncAPI 3, keep the linter you run on it.

Replace one step, keep the rest

Install the CLI, run apigenie lint beside the linter you have, and compare the two reports on the same file. Remove the old tool when they agree on what matters to you.