Two October releases, from translations to a fourth binary
Andriy Mykulyak · · 7 min read
If you installed API Genie before October, two releases sit between your binary and the current one: 0.9.0 on 10 October and 0.10.0 on 25 October. The changelog lists more than three hundred entries for the two. This is the shorter read: what each release adds, what you change when you upgrade, and what the binaries print, taken from a run of 0.10.0.
Since 0.10.0, apigenie --version lists the binaries installed next to it, and there are four:
$ apigenie --version
0.10.0
apigenie-generator 0.10.0
apigenie-server 0.10.0
apigenie-catalog 0.10.0
A script that compares the version reads the first line: apigenie --version | head -n 1.
0.9.0, 10 October
In the changelog’s words: API Genie 0.9.0 translates OpenAPI, Swagger 2.0, AsyncAPI, Protobuf and GraphQL files, and its mock server mocks and contract-checks HTTP, WebSocket, MQTT, gRPC and GraphQL APIs. The new GitHub Action mykulyak/api-genie-action installs the CLI in workflows on Linux, macOS and Windows.
- Translations for all five standards.
apigenie i18n extractandi18n applywork on OpenAPI, Swagger 2.0, AsyncAPI, Protobuf and GraphQL files. The texts are extracted keyed by JSON pointers, declaration names or schema coordinates, and the translations are put back without touching the rest of the file. - Contract testing across OpenAPI, Swagger, AsyncAPI, gRPC and GraphQL, with TLS.
apigenie testruns.httpfiles and generated requests against a live API. The mock server with--proxy-tosits between clients and a real server or broker and checks every request and response against the contract. Both report coverage, write JSON and JUnit reports, and fail CI with--fail-onand--min-coverage. The mock serves HTTPS, WSS and gRPC over TLS, and requests and upstreams can behttps://,wss://andmqtts://. - Code generation for five stacks. Clients and servers for TypeScript, Python, Go, Java and C#, from OpenAPI 3.0 to 3.2 and, for event-driven APIs, AsyncAPI 3.x. Every target is checked by a conformance suite: snapshots, the target’s own compiler and linter, and a run against the validating proxy. The generators are a separate executable,
apigenie-generator, installed with the CLI. - Web components for every spec type, and
generate docs. Theapg-*custom elements document OpenAPI, Swagger 2.0, AsyncAPI, Protobuf and GraphQL APIs, with Try it out for HTTP and GraphQL, built on the same engine as the CLI compiled to WebAssembly.apigenie-generator docscompiles any of these files, several at once, into a docs bundle that the components render into a static site.
What you change when you come from 0.8:
apigenie generateisapigenie-generator. Dropgeneratefrom the command line:apigenie generate client fetch spec.yaml -o outbecomesapigenie-generator client fetch spec.yaml -o out. The options and thecommands.generatesection of the configuration are unchanged.generate doc htmlis replaced byapigenie-generator docs, with no alias. The output is a docs bundle and an npm project, no longer an Astro project;npm install && npm run buildstill builds the site.- The binaries link Mbed TLS for
https://,wss://andmqtts://connections. Verifying servers needs the system’s CA certificates: the Docker images include them, a minimal image of your own needsca-certificates. - Telemetry is opt-in. The CLI writes no
.apigenie.telemetryfile and sends nothing; old files can be deleted. apigenie i18n FILE --output DESTbecomesapigenie i18n extract FILE --output DEST.lintexits with status 1 when errors remain, so a CI job that ran it for its report fails now. Lower the severities in the configuration to keep it passing.
0.10.0, 25 October
In the changelog’s words: the mock server is now apigenie-server, with a document store for CRUD resources and several services in one process, and a fourth binary, apigenie-catalog, keeps a repository’s API catalog. apigenie-generator applies OpenAPI overlays before generating, and the three binaries share one table of exit statuses.
-
apigenie-server, the mock server and validating proxy under its new name, with a dashboard at/__apigenie/ui(Traffic, Operations, Scenarios, Contract, Data and, for AsyncAPI, Channels), several services on one port with a prefix each, a document store (db.crud: autoresources, seeding, snapshots), session recording and replay (--record DIR,--replay DIR), client certificates, MQTT 5 properties, and validating proxies for Kafka and AMQP brokers. -
apigenie-catalog, a fourth binary, experimental:catalog listfinds the API specifications of a repository andcatalog initrecords them inapigenie.yaml. Run on a directory with the two Carpet Express documents of this blog’s series:$ apigenie-catalog list apigenie-catalog (experimental, outside the 1.0 compatibility promise) NAME FORMAT VERSION PATH COMMIT carpet-express-event-platform AsyncAPI 3.0.0 2.4.0 carpet-express.asyncapi.yaml - carpet-express-shipping-api OpenAPI 3.2.0 2.4.0 carpet-express.openapi.yaml - -
Code generation:
--overlay FILEon every OpenAPI and AsyncAPI target; the Elixir family (client elixirandserver phoenixfor OpenAPI and AsyncAPI,server absinthefor GraphQL,server elixir-grpcand the Elixir gRPC client for Protobuf);server mcp, experimental, a Model Context Protocol server from an OpenAPI document;server orpcat the conformance bar. -
apigenie testspeaks Kafka and AMQP (KAFKAandAMQPregions), GraphQL subscriptions over graphql-ws, gRPC client and bidirectional streams, MQTT 5 and mutual TLS. -
Towards 1.0: one table of exit statuses for the binaries,
formatVersionin every JSON report with published JSON Schemas, a JSON Schema forapigenie.yamlbehindapigenie config,config checkandconfig schema, configuration discovery without--config, the Compatibility page, and experimental labels on what is outside the coming promise. -
Linting and diffing: the OpenAPI format registry as the list of formats, with
schema-format-deprecated,schema-format-unknownand ahintseverity;diffknows sunset dates and no longer rates deprecating as breaking;apigenie evolve plan OLD NEW, experimental, plans an expand and contract migration. -
Also:
convert --from wsdl --to openapi31,i18n checkandi18n sync, OpenAPI formatting at every depth with layout options, Windows console colors, and a docs package published as@mykulyak/apigenie-docs.
The configuration check is the one to run first after upgrading. A file with a typo and a section that has no settings:
$ apigenie config check apigenie.yaml
apigenie.yaml:5:7: /commands/lint/ruels: unknown property 'ruels'; did you mean 'rules'?
apigenie.yaml:7:5: /commands/bundle: unknown property 'bundle'
$ echo $?
2
0.9.0 skipped both lines without a word. 0.10.0 reports them with the line, the column and the JSON pointer, and every command that loads the file exits with 2 until they are fixed.
The JSON reports are objects now, with a version:
$ apigenie lint --formatter json carpet-express.openapi.yaml | head -n 12
{
"formatVersion": 1,
"results": [
{
"filePath": "/work/carpet-express/carpet-express.openapi.yaml",
"messages": [
{
"column": 1,
"line": 1,
"message": "Too many paths found (27), maximum number is 8",
"ruleId": "paths-max-count",
"severity": "warning"
What you change when you come from 0.9:
apigenie-mockisapigenie-server, and its Docker image ismykulyak/apigenie-server. The old names keep working until 1.1 with a one-line notice on standard error:apigenie-mockis a symlink, and theAPIGENIE_MOCK_*variables are read when theAPIGENIE_SERVER_*variable of the same name is unset. The lastmykulyak/apigenie-mockimage only prints the new name and exits with 2. TheServerandViaheaders, the HAR creator and the contract report’sreportmember sayapigenie-server.- One table of exit statuses for
apigenie,apigenie-generatorandapigenie-server: 0 success, 1 findings, 2 a usage, input or unexpected error, 3 and 4 the server’s document and address errors, 5 a failed contract report. Errors that exited with 255 now exit with 2, so do unknown options and commands, missing files and configuration files that can’t be parsed;apigenie testexits with 2 instead of 3 when a request file or the specification can’t be read. lint --formatter jsonwrites{ "formatVersion": 1, "results": [...] }anddiff --report detailed --formatter jsonwrites{ "formatVersion": 1, "changes": [...] }; both were bare arrays. Read.resultsand.changes.diffno longer rates deprecating as breaking. Settingdeprecatedannounces a removal, and the removal is the breaking change, rated bysunset_passed. A gate that relied on the old rating setsoperation.deprecated: breakingincommands.diff.rules.- Seeded faker values change: the values of a
--seeddiffer from 0.9.0’s, usernames and emails are ASCII, and faker arguments are checked instead of clamped or ignored. apigenie formatkeeps JSON files JSON; setformat: yamlto convert them. The OpenAPI format configuration is checked, and therecommendedpreset reaches nested schemas, callbacks and the objects of OpenAPI 3.2, so expect a one-time diff when reformatting withextends: [recommended].- The configuration file is validated against its JSON Schema when it is loaded, and
apigenieandapigenie-generatorfindapigenie.yamlin the current directory or a parent up to the root of the repository. Pass--no-configto run with the defaults in a repository that has such a file. - The npm project that
apigenie-generator docswrites depends on@mykulyak/apigenie-docs. 0.9.0 wrote a package name that was never published, sonpm installfailed; replace the dependency or generate again. apigenie testconnects with MQTT 5 and checks the MQTT 5 properties against the AsyncAPI MQTT bindings; a region that publishes to a channel whose binding states properties gives them with# @propertylines or keeps 3.1.1 withversion: 3.1.1.
What is outside the promise
apigenie-catalog, evolve plan, convert and server mcp are experimental: their options and their output can change in a minor release, and their --help says so in the first line. Everything else in 0.10.0 is what 1.0 freezes, and the Compatibility page is the list.
Upgrade, then run apigenie config check on your apigenie.yaml. What it lists is what the old version ignored.