CLI

Sprawdź kontrakt, zanim zostanie scalony

apigenie lintuje, formatuje, porównuje i testuje kontraktowo opisy API, lokalnie i w CI: jeden plik binarny, jedna tabela kodów wyjścia.

Zlintuj swój pierwszy plik Czytaj dokumentację

Jedno CLI dla wszystkich formatów APIUżywaj tych samych poleceń lint, format i diff dla OpenAPI od 3.0 do 3.2, Swagger 2.0, AsyncAPI 3, Protobuf i GraphQL.
Kod 1 zatrzymuje pull requestBłędy lintera, zmiany łamiące zgodność i niesformatowane pliki kończą sprawdzenie kodem 1. GitHub Action pokazuje znaleziska jako adnotacje w pull requeście.
Żadnego środowiska do instalowania w CINatywne pliki binarne działają na macOS, Linuksie i Windows bez środowiska uruchomieniowego żadnego języka. Zainstaluj je na runnerze albo użyj obrazu Dockera.

Od edycji do scalenia

Ten sam plik binarny działa podczas edycji, przed commitem i w pull requeście, gdzie jego kod wyjścia decyduje, czy gałąź zostanie scalona.

Błędy lintera, niesformatowane pliki i zmiany łamiące zgodność kończą się kodem 1. Same ostrzeżenia kończą się kodem 0 i scalają.

Błędy lintera i zmiany łamiące zgodność, wychwycone

Błędy lintera, różnice w formatowaniu i zmiany łamiące zgodność zwracają kod 1; same ostrzeżenia lintera nie. Lint i diff dają też raporty JSON z --formatter json. GitHub Action uruchamia te sprawdzenia w pull requestach.

$ apigenie lint orders.yaml
  45:9   warning  Parameter should be named order_id                                parameter-naming
  53:7   error    Operation has no meaningful description                           operation-description-defined
  97:11  warning  String schema does not define constraints restricting its length  schema-constraints

  3 issues (1 errors, 2 warnings)
$ apigenie format --check orders.yaml
orders.yaml
1 file(s) would be reformatted.
$ git show main:orders.yaml > main.yaml
$ apigenie diff main.yaml orders.yaml
orders.yaml
  53  7  breaking  Modified operation GET /orders/{orderId}
  53  7  breaking  Removed parameter expand in query
$ echo $?
1

Co robi

lintSprawdza opisy API według wbudowanych zestawów reguł i zestawów w stylu Spectral, z bezpiecznymi poprawkami przez --fix. Raporty obejmują SARIF, JUnit, checkstyle i JSON.
formatSprowadza każdy plik do stylu Twojego zespołu: wcięcia, kolejność kluczy, style YAML. --check zatrzymuje build na niesformatowanych plikach.
diffPorównuje dwie wersje API, ocenia każdą zmianę jako łamiącą zgodność, niełamiącą lub niefunkcjonalną i zatrzymuje się na tych łamiących.
changelogBuduje changelog API z jego historii Git, per commit lub per tag wydania.
testUruchamia pliki .http albo żądania wygenerowane z kontraktu względem działającego API i sprawdza każdą wymianę względem kontraktu.
bundle, convert, overlayŁączy wieloplikowe API w jeden plik, konwertuje Swagger 2.0 do OpenAPI 3.2 oraz WSDL do OpenAPI 3.1 (eksperymentalne) i nakłada OpenAPI Overlays.
i18nWyodrębnia teksty API do tłumaczenia, sprawdza, czy tłumaczenie jest kompletne, i zapisuje przetłumaczone API.
evolvePlanuje zmianę łamiącą zgodność w etapach expand i contract, do przejrzenia przed wdrożeniem (eksperymentalne).
configJeden apigenie.yaml dla każdego polecenia, sprawdzany względem swojego JSON Schema, z podpowiedziami w Twoim edytorze.

Instalacja

Przez Homebrew na macOS i Linuksie albo przez npm wszędzie tam, gdzie działa Node.js. Oba instalują cztery pliki binarne, tak samo jak pakiety .deb i .rpm oraz archiwa na stronie Pobierz. Docker ma dwa obrazy: mykulyak/apigenie z CLI i generatorem oraz mykulyak/apigenie-server.

brew install mykulyak/apigenie/apigenie
npm install -g @mykulyak/api-genie

Instalowane razem z nim

Pakiety instalują cztery pliki wykonywalne w tej samej wersji.

Generatorapigenie-generator: klienci, serwery, dokumentacja i dane testowe z tych samych plików.
Serwerapigenie-server: mocki i walidujące proxy przed prawdziwym API.
Katalogapigenie-catalog: specyfikacje API w repozytorium, z ich właścicielami.

Zastosowania

Zlintuj swój pierwszy plik Czytaj dokumentację