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.
- Bez Node.js i Javy na runnerze
apigenie,apigenie-generator,apigenie-server,apigenie-catalogiapigenie-mcpto natywne pliki wykonywalne dla macOS na Apple silicon, Linuksa x64 i Windows x64. Homebrew, pakiet.deb,.rpmlub 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 lintczyta OpenAPI 3.0 do 3.2, Swagger 2.0, AsyncAPI 3, proto3 i GraphQL, z zestawem reguł na każdy standard w jednymapigenie.yaml. W zapisie poniżej jedno uruchomienie lintuje plik OpenAPI i plik AsyncAPI jednego API, aapigenie-serverserwuje 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 testiapigenie-server --proxy-towysył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/uiNarzę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.
| Zadanie | Dziś | Z API Genie | Co przenosisz |
|---|---|---|---|
| Lintowanie OpenAPI i AsyncAPI | Spectral 6.17 | apigenie lint | Reguł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 OpenAPI | Redocly CLI 2.72 | apigenie lint, apigenie bundle | Reguł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.35 | apigenie diff | Daty 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 serwery | OpenAPI Generator 7.x | apigenie-generator client, apigenie-generator server | Twoje 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 proxy | Prism 5.x | apigenie-server | Adres 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 Protobuf | Buf 1.75 | apigenie lint, apigenie diff, apigenie format | Reguł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.
| Dokument | Spectral | vacuum | apigenie lint |
|---|---|---|---|
| mały, 52 KiB | 0,727 | 0,050 | 0,023 |
| średni, 282 KiB | 0,795 | 0,118 | 0,028 |
| duży, 8,2 MiB | 3,897 | 1,993 | 0,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 konfiguracji
apigenie lint openapi.yamluruchamia zestawrecommendeddla standardu pliku.apigenie inittworzyapigenie.yamldla 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 lintiapigenie diffdziałają obok Buf, gdy Twój kod pochodzi zbuf generate. - Przenosisz swoje reguły i plikiReguły Spectral w
givenithentrafiają podcommands.lint.rulesbez zmian, poza kilkoma kluczami, które wymienia przewodnik, takimi jakaliasesioverrides. 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-ignoredla 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-mcpi polecenia eksperymentalne zostają poza tą obietnicą. - Raporty, które Twoje CI już czyta
--formatter sarifdo skanowania kodu, JUnit, checkstyle, TAP i JSON zformatVersion. 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 polecenia
apigenie-mcp(eksperymentalny) udostępnia agentom AI przez MCP sprawdzenia lintera, zmian łamiących zgodność, changelogu i formatowania,apigenie initdodaje doAGENTS.mdsekcję, która mówi im, jak je uruchamiać, a każda strona dokumentacji ma bliźniaczą wersję Markdown wymienioną wllms.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-a
apigenie lintczyta 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. Samespectral:oasispectral:asyncapisię nie ładują;recommendedma odpowiedniki około dwóch trzecich regułspectral:oas. - Redocly CLI: praca z platformą Redocly
push,project,preview,loginiejectdziałają z platformą Redocly, asplit,join,stats,scoreirespectnie mają odpowiednika.apigenie-generator docszastępujebuild-docsstatyczną witryną, którą hostujesz samodzielnie. - oasdiff: każda różnica jako dane
oasdiff diffwypisuje każdą różnicę jako YAML lub JSON bez wagi,--composedporównuje dwa zbiory plików jako jedno API, a--langtłumaczy komunikaty.apigenie diff --report detailed --formatter jsonjest najbliżej: po angielsku, po jednej parze plików naraz. - OpenAPI Generator: Kotlin, Dart, PHP, Ruby lub Scala
apigenie-generatorgeneruje 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 rozszerzeniax-apigenie, bez szablonów. - Prism: callbackiPrism wysyła żądania callback, które deklaruje operacja;
apigenie-servernie mockuje callbacków, webhooków ani linków. Prism serwuje też kolekcję Postmana jako dokument, czegoapigenie-servernie robi. - Buf: proto2, edycje i generowanie kodu
apigenie lint,diffiformatczytają tylko pliki proto3.buf generatez wtyczkami i Buf Schema Registry nie mają odpowiednika:apigenie-generatorgeneruje z plików.protokod tylko w Elixirze, klienta i serwer gRPC. Zostaw dla nich Buf, aapigenie lintiapigenie diffuruchamiaj obok. - Dokumentacja, którą Twój framework już serwujeKomponenty dokumentacji trafiają na Twoją stronę, a
apigenie-generator docsbuduje 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
.httpw repozytorium, któreapigenie testuruchamia, razem z żądaniami generowanymi z dokumentu, przeciwko działającemu serwerowi, a z--specsprawdza każde żądanie i odpowiedź względem kontraktu.apigenie test importzamienia 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.