API Genie CLI 0.9.0

Highlights

• Translations for all five standards. apigenie i18n extract and i18n apply work on OpenAPI, Swagger 2.0,
  AsyncAPI, Protobuf and GraphQL files: the texts are extracted keyed by JSON pointers, declaration names or schema
  coordinates, and translations are put back without touching the rest of the file
  (i18n).
• Contract testing across OpenAPI, Swagger, AsyncAPI, gRPC and GraphQL, with TLS. apigenie test runs .http
  files (HTTP, gRPC, WebSocket, MQTT and GraphQL requests) and generated requests against a live API, and
  apigenie-mock --proxy-to sits between clients and a real server or broker (HTTP, WebSocket, MQTT, gRPC, GraphQL),
  checking every request and response against the contract. Both report coverage, JSON and JUnit reports, and fail
  CI with --fail-on and --min-coverage. TLS is supported throughout: the mock serves HTTPS, WSS and gRPC over TLS
  (--tls-cert, --tls-key), and requests and upstreams can be https://, wss:// and mqtts://, verified against
  the system's CA certificates (--ca-cert, --insecure) (test,
  mock server).
• Code generation for five stacks. Clients and servers for TypeScript (fetch, Express, oRPC, WebSocket, Kafka on
  KafkaJS, Zod), Python (httpx, FastAPI, FastStream), Go (net/http, Kafka), Java (Spring clients and servers, Kafka)
  and C# (HttpClient, ASP.NET Core, Kafka), from OpenAPI 3.0–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
  apigenie-mock --proxy-to. The generators are a separate executable, apigenie-generator, installed with the CLI
  (apigenie-generator).
• Web components for every spec type, and generate docs. The apg-* custom elements
  (@mykulyak/apigenie-web-components on npm) document OpenAPI, Swagger 2.0, AsyncAPI, Protobuf/gRPC and GraphQL
  APIs, with Try it out for HTTP and GraphQL, built on the same engine as the CLI compiled to WebAssembly.
  apigenie-generator docs compiles any of these files, several at once, into a docs bundle that the components
  render into a static site (npm install && npm run build), with translations, the git changelog and example
  files; it replaces generate doc html (see Upgrading).

Upgrading

• apigenie generate is now apigenie-generator. The code generators moved out of apigenie into a separate
  executable, apigenie-generator, installed next to it by every archive and package, the npm package and Homebrew,
  and included in the mykulyak/apigenie Docker image (docker run --entrypoint apigenie-generator ...). Drop
  generate from the command line: apigenie generate client fetch spec.yaml -o out becomes
  apigenie-generator client fetch spec.yaml -o out. The options and the commands.generate section of the
  configuration file are unchanged; apigenie generate fails as an unknown command. The banners of generated files
  name the new command. The entries below still call the generators generate <target>. The design is ADR-123.
• generate doc html is replaced by generate docs, with no alias. apigenie-generator docs openapi.yaml -o docs
  replaces apigenie generate doc html openapi.yaml --output docs; it takes several inputs of mixed families (OpenAPI,
  Swagger 2.0, AsyncAPI, GraphQL, Protobuf) and makes one site, and -c/--config, --i18n LOCALE=FILE,
  --package-name and --package-version keep their meaning. The output is no longer an Astro project but a docs
  bundle (apigenie-docs.json and documents/<id>/document.<locale>.json, ADR-122) with a package.json that
  depends on @mykulyak/apigenie-web-components instead of @mykulyak/api-genie-doc-html-template;
  npm install && npm run build still builds the static site, now into dist/, prerendered from the web components.
  --bundle-only writes the bundle alone, for a site built by other means. The CLI does not run Node. The
  configuration section commands.generate.doc_html is commands.generate.docs: html_title_prefix is title,
  i18n.default_locale and i18n.prefix_default_locale move to the top of the section (the locales come from
  --i18n), changelog keeps its name (also --changelog), and documents lists the inputs (file, id,
  title, proto_paths, examples). pages, operations, resources, search, sidebar, html_meta,
  template, openapi_schema, request_code_examples, use_request_body_examples, generate_response_schema,
  use_response_examples and fail_on_generator_error described the Astro layout and have no replacement: the site
  has the layout of <apg-api-reference> (navigation with search, one page per operation and schema), themed with
  the components' CSS custom properties and ::part(). Generated Astro projects keep building with the template they
  depend on, but nothing regenerates them: run generate docs into a new directory.
• New dependency: Mbed TLS. apigenie and apigenie-mock link Mbed TLS 3.6 (Apache-2.0) for https://,
  wss:// and mqtts:// connections; release binaries grow by about 0.9 MB. Builds from source get it from vcpkg
  (mbedtls >= 3.6.2). Verifying servers needs the system's CA certificates: the Docker images now include them; in
  your own minimal images install ca-certificates. apigenie credits and apigenie license --library mbedtls list
  it.
• Telemetry is opt-in. The CLI no longer writes .apigenie.telemetry in the current directory, and sends
  nothing. Set APIGENIE_TELEMETRY_FILE to a path to keep a local telemetry log; old .apigenie.telemetry files
  can be deleted.
• i18n has subcommands. apigenie i18n FILE --output DEST becomes apigenie i18n extract FILE --output DEST.
• lint fails on errors. lint exits with status 1 when issues of severity error remain (after --fix), so CI
  jobs that ran it only for its report fail now; lower the severities in the configuration to keep them passing.
• apigenie-mock --stubs with a GraphQL schema or an AsyncAPI document exits with status 2 instead of ignoring
  the option.

Added

• generate docs documents OpenAPI, Swagger 2.0, AsyncAPI, GraphQL and Protobuf files, several at once, as one static
  site: it writes a docs bundle (apigenie-docs.json; per document and locale the resolved document, or the
  documentation model of AsyncAPI, GraphQL and Protobuf files; with --changelog the git changelog, as apigenie changelog computes it; the example files next to a GraphQL schema and those listed in the configuration) and the
  npm project that renders it with @mykulyak/apigenie-web-components (npm install && npm run build): prerendered
  pages with declarative shadow DOM that hydrate in the browser, Try it out, a sitemap, a locale switcher for the
  --i18n locales, a changelog page and the examples. --bundle-only writes the bundle alone. Internal: the
  docs_bundle library (compileDocsBundle), changelog_helpers (the changelog of any family, shared with the
  changelog command), and graphql_describe and protobuf_describe, which write the documentation models that the
  graphql and protobuf WebAssembly modules used to write themselves, as asyncapi_describe does for AsyncAPI.
  The design is ADR-122.
• generate server spring (OpenAPI) routes QUERY operations and additionalOperations such as COPY: their handlers
  carry @ExtensionMethod("QUERY"), which the generated ExtensionMethodConfiguration matches through a custom
  request condition of the request mapping (WebMvcRegistrations, or WebFluxRegistrations with reactive=true).
  pipeDelimited and spaceDelimited array query parameters are split on their separator (@DelimitedParameter),
  and query parameters with JSON content are read as JSON into their model (@JsonParameter), which is null and
  left unvalidated when the parameter is absent; both converters are registered by ParameterConversionConfiguration.
  Request media types whose bodies have different types get a handler each, named as the methods of
  generate client java (updateShipment for application/merge-patch+json, updateShipmentWithJsonPatch for the
  application/json-patch+json array). The new ApiExceptionHandler answers invalid requests with a 400 Problem
  (type, title, status, detail and, for constraint violations of the parameters, errors with the name,
  path and message of each), where a ConstraintViolationException used to answer 500. Conformance Level 3 of the
  target only expects the x-internal operation, which servers leave out, to fail.
• generate server aspnet (OpenAPI) falls back to the default mapping of a discriminator (defaultMapping, or
  x-defaultMapping before 3.2): unions are read and written by the converters of generate client csharp, written
  next to the abstract record and attached with [JsonConverter] instead of [JsonPolymorphic], so a missing or
  unmapped discriminator reads as the default type, and the discriminator may be anywhere in the object on .NET 8 too.
  Request media types whose bodies have different types get an endpoint and API method each, named as the methods of
  the C# client (UpdateShipment for application/merge-patch+json, UpdateShipmentJsonPatch for the
  application/json-patch+json array) and restricted to their media types with Accepts<T>(), so routing picks the
  endpoint by Content-Type; the JSON Patch array used to be bound as a ShipmentPatch object (400). Conformance Level 3
  of the target passes with only the x-internal operation, which the server leaves out, expected to fail.
• The codegen conformance runner decides that the x...

API Genie CLI 0.10.0

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.

Highlights

• 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 (ctx.db, db.crud: auto resources, seeding, snapshots), session
  recording and replay (--record DIR, --replay DIR), client certificates, MQTT 5 properties, and validating
  proxies for Kafka (--proxy-to kafka://) and AMQP (--proxy-to amqp://) brokers.
• apigenie-catalog (experimental), a fourth binary: catalog list finds the API specifications of a
  repository and catalog init records them in apigenie.yaml.
• Code generation: --overlay FILE on every OpenAPI and AsyncAPI target; the Elixir family (client elixir and
  server phoenix for OpenAPI and AsyncAPI, server absinthe for GraphQL, server elixir-grpc and the Elixir gRPC
  client for Protobuf); server mcp (experimental), a Model Context Protocol server from an OpenAPI document;
  server orpc at the conformance bar.
• apigenie test speaks Kafka and AMQP (KAFKA and AMQP regions), 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, formatVersion in every JSON report with published
  JSON Schemas, a JSON Schema for apigenie.yaml behind apigenie config, config check and config 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-unknown and a hint severity; diff knows sunset dates and no longer rates deprecating as
  breaking; apigenie evolve plan OLD NEW (experimental) plans an expand/contract migration.
• Also: convert --from wsdl --to openapi31, i18n check and i18n sync, OpenAPI formatting at every depth with
  layout options, Windows console colors, and a docs package published as @mykulyak/apigenie-docs.

Upgrading

• Upgrading from 0.9: apigenie-mock is now apigenie-server. The mock server and validating proxy is
  installed as apigenie-server by every archive and package, the npm package and Homebrew, and its Docker image is
  mykulyak/apigenie-server. The old names keep working until 1.1, each with a one-line deprecation notice on
  standard error: apigenie-mock is a symlink to apigenie-server (a copy in the Windows archive, a command of the
  npm package), and the APIGENIE_MOCK_* variables are read when the APIGENIE_SERVER_* variable of the same name
  is unset. The last mykulyak/apigenie-mock image (latest and this version) only prints the new name and exits
  with 2; older tags are unchanged. apigenie-server.yaml is read before apigenie-mock.yaml, which still works;
  commands.mock, the x-apigenie-mock extensions, the X-Apigenie-Mock-* headers and the /__apigenie admin API
  are unchanged. What the server sends says apigenie-server instead: the Server and Via headers, the HAR
  creator, the admin status name, the Basic realm, the MQTT client ids, and the contract report's report
  member (apigenie-server-contract) and JUnit suite name (apigenie-server contract). The reference page moved to
  server; the old address redirects. The design is ADR-147.

• One table of exit statuses for apigenie, apigenie-generator and apigenie-server. 0 success, 1 findings
  (lint errors, breaking changes, format --check differences, i18n apply --strict unknown keys, overlay --validate problems), 2 a usage, input or unexpected error, 3 and 4 apigenie-server's document and address
  errors, 5 a failed contract report (apigenie-server, apigenie test). The 1.0 compatibility promise freezes it.
  Scripts that check for the old numbers need these changes:

  • errors that exited with 255 (-1) now exit with 2: unreadable or invalid input files in bundle, convert,
    changelog, diff, i18n, lint and overlay, bad configurations, and every error of apigenie-generator;
  • errors that exited with 1 now exit with 2: unknown options and commands, missing files, configuration files that
    can't be parsed, format on a file with syntax errors or an unsupported document, bundle of a .proto file
    with errors, license --library with an unknown name, and unexpected errors in apigenie-server and apigenie test;
  • apigenie test exits with 2 instead of 3 when a request file, an environment file or the specification can't be
    read or parsed;
  • apigenie and apigenie-generator without a command, or with an unknown one, exit with 2 (255 before) and
    print the help of the command above it on the standard error.

  apigenie-server keeps 3, 4, 5 and 130. The design is ADR-141
  (exit status).

• --version lists the binaries installed next to it. apigenie --version prints the version on its first line,
  then apigenie-generator VERSION and apigenie-server VERSION for those found in the same directory (the same for
  the other two binaries). Scripts comparing the version should read the first line: apigenie --version | head -n 1. The GitHub Action, the Homebrew formula and the release workflows do. Subcommands no longer have a --version
  of their own (apigenie lint --version printed 1.0).

• lint --formatter json and diff --report detailed --formatter json write an object. Lint JSON is
  { "formatVersion": 1, "results": [...] } and the detailed diff report { "formatVersion": 1, "changes": [...] };
  both were bare arrays. Read .results and .changes instead
  (compatibility).

• diff no longer rates deprecating as breaking. In the recommended rules, setting or clearing deprecated on an
  operation, a parameter, a header or a schema is non_breaking: it announces a removal, and the removal is the
  breaking change (rated by sunset_passed, see Added). Gates that relied on it should set operation.deprecated: breaking (and parameter, header, schema) in commands.diff.rules. The design is ADR-172.

• Seeded faker values change. Faker now draws its values with algorithms of its own, the same on every platform, and
  name, email and other values of a --seed differ from 0.9.0's. Usernames and emails are ASCII (Cieślar becomes
  Cieslar), and date.between is a range ({date.between: {from: 2024-01-01, to: 2024-12-31}}) rather than an alias of
  date.recent.

• Faker arguments are checked. x-faker, @mock(faker:, args:), graphql.fields and fake() reject arguments a
  provider doesn't take, of the wrong type or out of bounds (a negative length, a probability above 1) with faker's
  message, where they were clamped or ignored.

• apigenie format keeps the format of OpenAPI, Swagger and AsyncAPI files without a configuration. Formatting
  api.json with no --config used to write api.yaml next to it; JSON files now stay JSON. Set format: yaml to
  convert them.

• The OpenAPI format configuration is checked. Unknown keys (indnet), unknown objects in property_order,
  indents outside 2 to 9 and unknown output formats are reported with their line and column, and nothing is
  formatted; they used to be ignored or to abort the command.

• The recommended OpenAPI preset changes more of a document. It now reaches nested schemas, inline callbacks
  and the objects of OpenAPI 3.2, sorts the path templates of paths (its paths: sorted had no effect), orders
  more schema keywords ($ref, $id, $defs, default, examples, readOnly, writeOnly, deprecated...) and
  the fields of 3.2 objects, and orders Reference Objects by reference. Expect a one-time diff when reformatting
  with extends: [recommended]. property_order.responses applies to the status codes of operations; the names of
  components.responses follow the new componentNames key.

• The configuration file is validated against a JSON Schema when it is loaded, by apigenie,
  apigenie-generator and apigenie-server. Settings that were silently ignored are now errors (exit status 2) with
  the line, the column and the JSON pointer of the value: unknown keys under commands.* (the OpenAPI, AsyncAPI and
  Swagger linters, and the WebSocket generators, used to skip them), sections of commands that have no settings
  (commands.bundle, commands.changelog: changelog uses commands.diff), and values of the wrong type.
  apigenie config check lists the errors of a file; fix them, or remove the settings that did nothing. The design is
  ADR-145.

• apigenie and apigenie-generator find the configuration file without --config: apigenie.yaml (.yml,
  .json, or .apigenie.*) in the current directory or a parent up to the root of the git repository. Pass
  --no-config to run with the defaults, as before, in a repository that has such a file. apigenie-server falls
  back to the same file after its own apigenie-server.yaml and apigenie-mock.yaml.

• The docs package is @mykulyak/apigenie-docs. The npm project that apigenie-generator docs writes now
  depends on @mykulyak/apigenie-docs (^0.1.0), the new name of the web components package. 0.9.0 wrote
  @mykulyak/apigenie-web-components into ...

v0.8.2-alpha

Full Changelog: cli-0.8.0...cli-0.8.2

v0.8.0-alpha

Full Changelog: https://github.com/mykulyak/api-genie/commits/cli-0.8.0