How-to guidesCatalog the APIs of a repository

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, and keeps the catalog current.

You need the CLI installed; the Quickstart shows how. apigenie-catalog is experimental: release tags, 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.

Use the catalog in your tools

--json prints the catalog with a published schema: the name, title, format, version, path and owner 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