Catalog the APIs of a repository
A repository with more than a few APIs raises questions nobody can answer quickly: which APIs are
there, which version is which, and who to ask about each. apigenie-catalog answers them from the
repository itself, with nothing to host and nothing to upload. This guide lists the APIs of a
repository, records their names and owners, keeps the catalog current and releases a
specification as a Git tag.
You need the CLI installed; the Quickstart shows how. apigenie-catalog is
experimental: pinned consumers and catalogs that
span several repositories will add options.
List the specifications
Run it anywhere in the repository; no configuration is needed:
apigenie-catalog list
NAME FORMAT VERSION PATH COMMIT
order-events AsyncAPI 3.0.0 2.0.0 apis/events.json 96175d8 2026-10-12
orders-api OpenAPI 3.1.0 1.2.0 apis/orders/openapi.yaml 4d0c2e1 2026-10-14
schema GraphQL - graphql/schema.graphql 96175d8 2026-10-12
acme-pricing-v1 Protobuf proto3 - proto/pricing.proto 96175d8 2026-10-12
It looks at the files Git tracks, so build output and ignored files stay out, and finds OpenAPI,
AsyncAPI and Swagger documents by their content, every .proto file, and GraphQL files with type
definitions. Each row has a name derived from the specification (its title, its Protobuf package or
its file name), its format and version, its path and its last commit. Give a directory to list part
of the repository: apigenie-catalog list apis/.
Give each API a name and an owner
A derived name changes when the title or the file does, and an owner can’t be derived at all.
apigenie-catalog init writes a catalog section into apigenie.yaml, with one entry per
specification:
apigenie-catalog init
catalog:
specs:
- name: order-events
path: apis/events.json
owner: null
- name: orders-api
path: apis/orders/openapi.yaml
owner: null
Fill in the owners, and change a name where the derived one isn’t right. From then on the name stays
when the file moves: change the path and keep the name. Commit the file: a new owner is now a
change that is reviewed like any other.
Leave files out of the catalog, such as test fixtures, with patterns under catalog.exclude; see
the catalog section of the configuration.
Keep it current
Run init again after adding specifications. New ones are added, the entries you edited stay as
they are, and the entries whose files are gone are reported; --prune removes them:
$ apigenie-catalog init
Updated /home/me/specs/apigenie.yaml: 2 added, 4 kept, 1 not found
added apis/billing.yaml
added apis/orders-v2.yaml
not found legacy/swagger.yaml
Remove the entries of the files that are gone with --prune.
To catch a specification added without an entry, let CI run init --dry-run, which prints the file
instead of writing it, and compare the result with the committed apigenie.yaml.
Release a specification
apigenie-catalog release (since 0.12.0) makes a release a Git tag, so everyone who clones the
repository has it. Bump info.version in the pull request that changes the API, merge it, then
tag:
$ apigenie-catalog release orders-api 1.1.0 --push
Tagged orders-api-1.1.0 at b2e21b5 Release 1.1.0 of the Orders API (previous release: 1.1.0-rc.1, tag orders-api-1.1.0-rc.1)
Pushed orders-api-1.1.0 to origin
The command refuses to tag when the version is not above the latest release, the file has changes
that are not committed, or its info.version is not 1.1.0. The tag and the info.version of an
OpenAPI, AsyncAPI or Swagger document then name the same version. apigenie-catalog versions
lists the releases:
$ apigenie-catalog versions orders-api
VERSION TAG COMMIT
1.1.0 orders-api-1.1.0 b2e21b5 2026-11-02
1.1.0-rc.1 orders-api-1.1.0-rc.1 c121c1b 2026-10-28
1.0.0 orders-api-1.0.0 12e9f3d 2026-10-12
The tags are revisions, so
apigenie changelog apis/orders/openapi.yaml --from orders-api-1.0.0 --to orders-api-1.1.0 lists
the changes between two releases (changelog).
Teams that tag orders-api/v1.4.0 set catalog.tags.pattern to {name}/v{version}.
Mark an API that is on its way out in the catalog section, so that the catalog says so and a retired one can’t be released by mistake:
catalog:
specs:
- name: legacy-billing
path: apis/legacy/billing.yaml
owner: team-finance
lifecycle: deprecated
sunset: 2027-03-31
$ apigenie-catalog list
NAME FORMAT VERSION OWNER LIFECYCLE PATH COMMIT
legacy-billing OpenAPI 3.0.3 4.2.0 team-finance deprecated (2027-03-31) apis/legacy/billing.yaml a510f31 2026-11-02
orders-api OpenAPI 3.1.0 1.1.0 team-commerce active apis/orders/openapi.yaml b2e21b5 2026-11-02
acme-pricing-v1 Protobuf proto3 - - active proto/pricing.proto 12e9f3d 2026-10-12
Once lifecycle: retired replaces deprecated, apigenie-catalog release legacy-billing 4.2.0
prints legacy-billing is retired (catalog section); a retired specification is not released and
legacy-billing 4.2.0 is not released on the standard error, and exits with status 2.
Use the catalog in your tools
--json prints the catalog with a published schema:
the name, title, format, version, path, owner and lifecycle of each specification, its last
commit, and whether the catalog section lists it. Scripts can lint or diff every API of the repository from it,
or feed a dashboard of owners:
apigenie-catalog list --json > catalog.json
Next steps
apigenie-catalog: every option and the JSON report.- changelog: the history of each specification from git.
- Lint and format API descriptions: the same rules for every API the catalog lists.