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.
- No Node.js or Java on the runner
apigenie,apigenie-generator,apigenie-server,apigenie-catalogandapigenie-mcpare native executables for macOS on Apple silicon, Linux x64 and Windows x64. Homebrew, a.deb, an.rpmor 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
apigenie lintreads OpenAPI 3.0 to 3.2, Swagger 2.0, AsyncAPI 3, proto3 and GraphQL, with a ruleset per standard in oneapigenie.yaml. In the transcript below, one run lints the OpenAPI file and the AsyncAPI file of one API, andapigenie-serverserves 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_FILEnames one.apigenie testandapigenie-server --proxy-tosend 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/uiThe 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 |
| 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 |
| 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 |
| 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 |
| 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 |
| 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 |
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 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
apigenie lint openapi.yamlruns therecommendedruleset of the file's standard.apigenie initwrites anapigenie.yamlfor 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 lintandapigenie diffrun beside Buf when your code comes frombuf generate. - Your rules and your files carry overSpectral rules in
givenandthengo undercommands.lint.rulesas they are, apart from the few keys the guide lists, such asaliasesandoverrides. 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-ignorefor 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 --checkdifferences. 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-mcpand the experimental commands stay outside that promise. - Reports your CI already reads
--formatter sariffor code scanning, JUnit, checkstyle, TAP and JSON with aformatVersion. 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
apigenie-mcp(experimental) serves the lint, breaking-change, changelog and format checks to coding agents over MCP,apigenie initadds toAGENTS.mdthe section that tells them how to run the checks, and every page of Docs has a Markdown twin listed inllms.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
apigenie lintreads 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:oasandspectral:asyncapithemselves don't load;recommendedhas the counterparts of about two thirds ofspectral:oas. - Redocly CLI, for its platform
push,project,preview,loginandejectwork with the Redocly platform, andsplit,join,stats,scoreandrespecthave no counterpart.apigenie-generator docsreplacesbuild-docswith a static site you host yourself. - oasdiff, for every difference as data
oasdiff diffprints every difference as YAML or JSON without a severity,--composedcompares two sets of files as one API, and--langtranslates the messages.apigenie diff --report detailed --formatter jsonis the nearest, in English, one pair of files at a time. - OpenAPI Generator, for Kotlin, Dart, PHP, Ruby or Scala
apigenie-generatorwrites 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 thex-apigenieextensions, with no templates. - Prism, for callbacksPrism sends the callback requests an operation declares;
apigenie-serverdoes not mock callbacks, webhooks or links. Prism also serves a Postman collection as the document, whichapigenie-serverdoes not. - Buf, for proto2, editions and code generation
apigenie lint,diffandformatread proto3 files only.buf generatewith its plugins and the Buf Schema Registry have no counterpart: from.protofiles,apigenie-generatorwrites code in Elixir only, a gRPC client and a gRPC server. Keep Buf for them, and runapigenie lintandapigenie diffbeside it. - A reference your framework already servesThe doc components go into a page of yours, and
apigenie-generator docsbuilds 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
.httpfiles in the repository, whichapigenie testruns, with the ones it generates from the document, against a live server, and with--specchecks every request and response against the contract.apigenie test importturns a Postman collection into.httpfiles. - 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.