# One install instead of a tool per job

Source: https://api-genie.dev/why

Why API Genie. 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.

- [No Node.js or Java on the runner](/downloads): `apigenie`, `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 events](/docs/linter.md): `apigenie 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 machine](/docs/faq.md#does-anything-leave-my-machine): 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. `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" }`.

```shellsession
$ 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.

| Job | Today | With API Genie | What carries over |
| --- | --- | --- | --- |
| Lint OpenAPI and AsyncAPI | Spectral 6.17 | `apigenie lint` | The 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](/docs/guides/migrate-from-spectral.md) |
| Lint and bundle OpenAPI | Redocly CLI 2.72 | `apigenie lint`, `apigenie bundle` | The `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](/docs/guides/migrate-from-redocly.md) |
| Breaking changes | oasdiff 1.35 | `apigenie diff` | The `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](/docs/guides/migrate-from-oasdiff.md) |
| Clients and servers | OpenAPI Generator 7.x | `apigenie-generator client`, `apigenie-generator server` | Your 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](/docs/guides/migrate-from-openapi-generator.md) |
| Mock and validation proxy | Prism 5.x | `apigenie-server` | The 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](/docs/guides/migrate-from-prism.md) |
| Lint, diff and format Protobuf | Buf 1.75 | `apigenie lint`, `apigenie diff`, `apigenie format` | The lint rules by name and the `buf.yaml` settings, as sections of `apigenie.yaml`; `buf generate` stays. [Migrate from Buf](/docs/guides/migrate-from-buf.md) |

## 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.

| Document | Spectral | vacuum | `apigenie lint` |
| --- | --- | --- | --- |
| small, 52 KiB | 0.727 | 0.050 | 0.023 |
| medium, 282 KiB | 0.795 | 0.118 | 0.028 |
| large, 8.2 MiB | 3.897 | 1.993 | 0.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](/docs/reference/cli/lint-performance.md) 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 configuration](/docs/reference/cli/init.md): `apigenie 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 agree](/docs/guides.md#coming-from-another-tool): Every 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 over](/docs/guides/migrate-from-spectral.md#carry-your-custom-rules-over): Spectral 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 pipeline](/docs/reference/cli.md#exit-status): 0 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](/docs/ci.md): `--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 commands](/docs/reference/cli/mcp.md): `apigenie-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 URL](/docs/guides/migrate-from-spectral.md#keep-a-shared-ruleset-file): `apigenie 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 platform](/docs/guides/migrate-from-redocly.md#what-stays-with-redocly): `push`, `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 data](/docs/guides/migrate-from-oasdiff.md#what-stays-with-oasdiff): `oasdiff 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 Scala](/docs/guides/migrate-from-openapi-generator.md#what-has-no-counterpart): `apigenie-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 callbacks](/docs/guides/migrate-from-prism.md#what-has-no-counterpart): Prism 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 generation](/docs/guides/migrate-from-buf.md#what-stays-with-buf): `apigenie 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 serves](/use-cases/api-docs): The 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 requests](/docs/reference/cli/test/import.md): The 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 have](/docs/faq.md#which-versions-of-the-standards-do-the-tools-read): The 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.
