Dlaczego API Genie

Jedna instalacja zamiast narzędzia na każde zadanie

Twoje repozytorium lintuje Spectralem, mockuje Prismem i generuje klienta OpenAPI Generatorem: trzy narzędzia, trzy wersje do przypięcia, Node.js i Java na runnerze. API Genie robi te trzy rzeczy z jednej instalacji i do tego sprawdza zmiany łamiące zgodność.Fakty o innych narzędziach pochodzą z przewodników migracji (Spectral 6.17, Redocly CLI 2.72, oasdiff 1.35, OpenAPI Generator 7.x, Prism 5.x, Buf 1.75), sprawdzonych 9 listopada 2026, a czasy ze strony o wydajności lintera (Spectral 6.17.1, vacuum 0.39.3, pomiar z 8 listopada 2026). Zapis sesji pochodzi z API Genie 0.12.0.

Zainstaluj CLIPrzejdź z narzędzia, którego używasz
  • Bez Node.js i Javy na runnerzeapigenie, apigenie-generator, apigenie-server, apigenie-catalog i apigenie-mcp to natywne pliki wykonywalne dla macOS na Apple silicon, Linuksa x64 i Windows x64. Homebrew, pakiet .deb, .rpm lub archiwum instalują je bez Node.js i Javy; plik dla Linuksa jest linkowany statycznie. Spectral działa na Node.js, OpenAPI Generator na Javie 11 lub nowszej. Pakiet npm wymaga Node.js 18 lub nowszego i uruchamia te same pliki.
  • Jedno uruchomienie dla REST API i jego zdarzeńapigenie lint czyta OpenAPI 3.0 do 3.2, Swagger 2.0, AsyncAPI 3, proto3 i GraphQL, z zestawem reguł na każdy standard w jednym apigenie.yaml. W zapisie poniżej jedno uruchomienie lintuje plik OpenAPI i plik AsyncAPI jednego API, a apigenie-server serwuje oba.
  • Nic nie wychodzi poza Twój komputerNarzędzia wiersza poleceń nie otwierają żadnego połączenia, chyba że polecenie wskazuje serwer: nic nie jest nigdzie wysyłane, a plik telemetrii nie powstaje, chyba że wskazuje go APIGENIE_TELEMETRY_FILE. apigenie test i apigenie-server --proxy-to wysyłają żądania do serwera, który wskażesz, i do nikogo więcej.

Lintowanie, porównanie, mock i generowanie z jednej instalacji

orders.yaml opisuje API zamówień w OpenAPI 3.1, order-events.yaml zdarzenia, które ono wysyła, w AsyncAPI 3.0, a main.yaml to wersja orders.yaml z gałęzi main. Jeden apigenie.yaml, z extends: [recommended] i jedną wyłączoną regułą, obowiązuje dla obu plików. apigenie lint kończy się kodem 1 z powodu błędu, apigenie diff z powodu zmiany łamiącej zgodność, a apigenie diff --report status --formatter json main.yaml orders.yaml daje skryptowi ten sam werdykt: { "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

Narzędzie, którego używasz dziś, i co z niego przeniesiesz

Każdy wiersz prowadzi do przewodnika migracji, w którym znajdziesz resztę. Fakty o drugim narzędziu dotyczą wersji, którą przewodnik wymienia.

ZadanieDziśZ API GenieCo przenosisz
Lintowanie OpenAPI i AsyncAPISpectral 6.17apigenie lintReguły w given i then z wbudowanymi funkcjami, Twoje funkcje JavaScript i reguły spectral:oas zmapowane po nazwie. Zestaw reguł rozszerzany z URL-a lub pakietu npm kopiujesz do repozytorium. Migracja ze Spectral (ang.)
Lintowanie i łączenie OpenAPIRedocly CLI 2.72apigenie lint, apigenie bundleReguły recommended po nazwie, dekoratory jako OpenAPI Overlays, a od 0.13.0 także .redocly.lint-ignore.yaml jako .apigenie.lint-ignore.yaml. Migracja z Redocly CLI (ang.)
Zmiany łamiące zgodnośćoasdiff 1.35apigenie diffDaty x-sunset, od których usunięcie przestaje łamać zgodność, i sprawdzenia jako reguły, które dostrajasz; --deprecation-days-stable nie ma odpowiednika. Kod wyjścia to 1 przy zmianie łamiącej zgodność, bez --fail-on. Migracja z oasdiff (ang.)
Klienci i serweryOpenAPI Generator 7.xapigenie-generator client, apigenie-generator serverTwoje pliki implementacji, tworzone tylko wtedy, gdy ich brakuje; .openapi-generator-ignore dla celów Spring, Java i FastAPI; projekt Spring lub FastAPI generowany ponownie w miejscu. Migracja z OpenAPI Generator (ang.)
Mock i walidujące proxyPrism 5.xapigenie-serverAdres http://127.0.0.1:4010, Prefer: code=, example= i dynamic=, 422 ze szczegółami problemu oraz proxy jako drugi tryb tego samego polecenia. Migracja z Prism (ang.)
Lintowanie, porównywanie i formatowanie ProtobufBuf 1.75apigenie lint, apigenie diff, apigenie formatReguły lintera po nazwie i ustawienia buf.yaml jako sekcje apigenie.yaml; buf generate zostaje. Migracja z Buf (ang.)

Szybszy niż Spectral i vacuum na tych samych regułach

Mediana czasu w sekundach dla 26 reguł spectral:oas, które trzy lintery implementują natywnie, na Apple M1, zmierzona 8 listopada 2026 ze Spectral 6.17.1, vacuum 0.39.3 i apigenie lint zbudowanym ze źródeł po 0.12.0.

DokumentSpectralvacuumapigenie lint
mały, 52 KiB0,7270,0500,023
średni, 282 KiB0,7950,1180,028
duży, 8,2 MiB3,8971,9930,149

Na dużym dokumencie, REST API GitHuba, apigenie lint sprawdza też 243 webhooki pod x-webhooks, które Spectral i vacuum pomijają, więc trzy raporty mają różne liczby znalezisk. Z 10 własnymi regułami jako funkcjami JavaScript na tym samym dokumencie potrzebuje 2,234 s wobec 3,820 s Spectrala i 5,203 s vacuum. Szczytowe zużycie pamięci na dużym dokumencie: 87 do 115 MiB dla apigenie lint, 570 do 1860 MiB dla Spectrala, 1,3 do 2,2 GiB dla vacuum. Wydajność lintera (ang.) ma czasy dla czterech zestawów reguł i liczby znalezisk. Podaje też polecenia, którymi zmierzysz czas trzech linterów na własnych dokumentach, z ich domyślnymi regułami lub Twoim zestawem reguł dla Spectrala.

Wdrażaj po jednym sprawdzeniu

  • Zacznij bez konfiguracjiapigenie lint openapi.yaml uruchamia zestaw recommended dla standardu pliku. apigenie init tworzy apigenie.yaml dla opisów API, które znajdzie w repozytorium, i zachowuje pliki, które już tam są.
  • Zostaw stare narzędzie, aż raporty się zgodząKażdy przewodnik migracji zaczyna od zainstalowania obu narzędzi, uruchamia je na tym samym pliku i usuwa stare w ostatnim kroku. apigenie lint i apigenie diff działają obok Buf, gdy Twój kod pochodzi z buf generate.
  • Przenosisz swoje reguły i plikiReguły Spectral w given i then trafiają pod commands.lint.rules bez zmian, poza kilkoma kluczami, które wymienia przewodnik, takimi jak aliases i overrides. Funkcja JavaScript przechodzi bez zmian, chyba że czyta plik, pobiera URL lub ustawia timer. Generator tworzy Twoje pliki implementacji tylko wtedy, gdy ich brakuje, i czyta .openapi-generator-ignore dla Spring, Javy i FastAPI.

Jedna tabela kodów wyjścia, dla CI i dla agentów

  • Ten sam kod wyjścia w każdym pipelinie0 przy sukcesie, 1 przy znaleziskach: błędach lintera, zmianach łamiących zgodność, różnicach format --check. 2 przy błędzie użycia lub wejścia. Ta sama tabela dla pięciu plików wykonywalnych. Od 1.0.0 polecenia, opcje, kody wyjścia i wyjścia JSON podlegają wersjonowaniu semantycznemu; apigenie-mcp i polecenia eksperymentalne zostają poza tą obietnicą.
  • Raporty, które Twoje CI już czyta--formatter sarif do skanowania kodu, JUnit, checkstyle, TAP i JSON z formatVersion. GitHub Action pokazuje problemy jako adnotacje przy plikach pull requesta; strony o CI konfigurują te same sprawdzenia lintera, formatowania i zmian łamiących zgodność dla GitLaba, Azure Pipelines, Bitbucket Pipelines, CircleCI i Jenkinsa.
  • Agenci uruchamiają te same poleceniaapigenie-mcp (eksperymentalny) udostępnia agentom AI przez MCP sprawdzenia lintera, zmian łamiących zgodność, changelogu i formatowania, apigenie init dodaje do AGENTS.md sekcję, która mówi im, jak je uruchamiać, a każda strona dokumentacji ma bliźniaczą wersję Markdown wymienioną w llms.txt.

Gdzie inne narzędzie jest lepszym wyborem

Czego API Genie nie robi, narzędzie po narzędziu; każda karta prowadzi do strony, na której znajdziesz całość.

  • Spectral: wspólny zestaw reguł z npm lub spod URL-aapigenie lint czyta pliki zestawów reguł tylko z dysku. Zestaw, który Twoje repozytoria rozszerzają z URL-a lub pakietu npm, kopiujesz do każdego z nich. Same spectral:oas i spectral:asyncapi się nie ładują; recommended ma odpowiedniki około dwóch trzecich reguł spectral:oas.
  • Redocly CLI: praca z platformą Redoclypush, project, preview, login i eject działają z platformą Redocly, a split, join, stats, score i respect nie mają odpowiednika. apigenie-generator docs zastępuje build-docs statyczną witryną, którą hostujesz samodzielnie.
  • oasdiff: każda różnica jako daneoasdiff diff wypisuje każdą różnicę jako YAML lub JSON bez wagi, --composed porównuje dwa zbiory plików jako jedno API, a --lang tłumaczy komunikaty. apigenie diff --report detailed --formatter json jest najbliżej: po angielsku, po jednej parze plików naraz.
  • OpenAPI Generator: Kotlin, Dart, PHP, Ruby lub Scalaapigenie-generator generuje z OpenAPI 8 klientów i 11 serwerów, w tym 6 eksperymentalnych; OpenAPI Generator ma 172 generatory, wśród nich klientów w Kotlinie, Darcie, PHP, Ruby i Scali, oraz szablony do zmiany wyniku. API Genie zmienia wynik przez opcje, nakładkę i rozszerzenia x-apigenie, bez szablonów.
  • Prism: callbackiPrism wysyła żądania callback, które deklaruje operacja; apigenie-server nie mockuje callbacków, webhooków ani linków. Prism serwuje też kolekcję Postmana jako dokument, czego apigenie-server nie robi.
  • Buf: proto2, edycje i generowanie koduapigenie lint, diff i format czytają tylko pliki proto3. buf generate z wtyczkami i Buf Schema Registry nie mają odpowiednika: apigenie-generator generuje z plików .proto kod tylko w Elixirze, klienta i serwer gRPC. Zostaw dla nich Buf, a apigenie lint i apigenie diff uruchamiaj obok.
  • Dokumentacja, którą Twój framework już serwujeKomponenty dokumentacji trafiają na Twoją stronę, a apigenie-generator docs buduje statyczną witrynę przez npm. Jeśli strona Swagger UI, którą serwuje Twoja aplikacja, wystarcza czytelnikom, zostaw ją; witryna dodaje zdarzenia, usługi GraphQL i Protobuf, wyszukiwanie i Try it out.
  • Postman, Insomnia lub Bruno: kolekcja zapisanych żądańTry it out w edytorze wysyła żądanie z podglądu operacji, ale żadna aplikacja API Genie nie przechowuje kolekcji zapisanych żądań: Twoje trafiają do plików .http w repozytorium, które apigenie test uruchamia, razem z żądaniami generowanymi z dokumentu, przeciwko działającemu serwerowi, a z --spec sprawdza każde żądanie i odpowiedź względem kontraktu. apigenie test import zamienia kolekcję Postmana w pliki .http.
  • Narzędzia do AsyncAPI 2, które już maszCLI czyta AsyncAPI 3 i odrzuca dokumenty AsyncAPI 2. Edytor importuje dokument AsyncAPI 2.x i pokazuje konwersję jako diff; dopóki repozytorium nie przejdzie na AsyncAPI 3, zostaw linter, którego na nim używasz.

Zastąp jeden krok, resztę zostaw

Zainstaluj CLI, uruchom apigenie lint obok lintera, którego używasz, i porównaj oba raporty na tym samym pliku. Stare narzędzie usuń, gdy raporty zgodzą się w tym, co dla Ciebie ważne.