changelog

Builds the changelog of an OpenAPI, Swagger, AsyncAPI, Protobuf or GraphQL file from its git history.

Usage

apigenie changelog [OPTIONS] FILE

Description

This command compares the consecutive versions of an OpenAPI, Swagger, AsyncAPI, Protobuf or GraphQL file stored in a git repository, and describes what changed for API consumers: added, removed, deprecated and changed operations, servers and metadata, for AsyncAPI the channels, for Protobuf the methods, messages, enums and services, and for GraphQL the fields of the root operation types and the types and directives of the schema. Each change is rated as breaking, non-breaking or non-functional, with the same rules as the diff command.

The command runs git, which must be installed. The file must be in a git repository, and only its committed versions are compared.

Revisions

By default, the changelog has an entry for every commit that changes the file or one of the files it references. Commits that change neither, and commits whose changes don’t affect the API (e.g. reformatting), are left out. With --revisions tags, the changelog has an entry for every release tag instead, comparing each release with the previous one.

# every commit
apigenie changelog api/openapi.yaml

# every release tagged v1.0.0, v1.1.0, ..., and the changes made since the last one
apigenie changelog api/openapi.yaml --revisions tags --tag-pattern 'v*' --unreleased

Only the first parent of merge commits is followed, so a merged branch appears as a single entry: its merge commit.

The first version of the file starts the changelog, and lists the operations the API had then. With --from, the changelog starts after the given revision instead, e.g. the last release. --to sets the last revision, which is HEAD by default.

apigenie changelog api/openapi.yaml --from v2.0.0

Files split into many documents

References to other files (e.g. $ref: 'schemas/pet.yaml') are followed in each version, so a change of a referenced file is a change of the API. By default, the commits changing the file or the files it references in the last revision are compared. --path selects the commits changing other paths instead, e.g. files that were referenced in older versions only:

apigenie changelog api/openapi.yaml --path api

References to URLs and to files outside the repository aren’t supported.

Changes of operations

With --by operation, the changes are grouped by operation, with the history of each one, newest first. --operation selects the operations to show, by method and path, by path or by operation id, and can be repeated:

apigenie changelog api/openapi.yaml --by operation --operation 'GET /pets' --operation createPet

Operations are identified by their method and path, so moving an operation to another path shows as removing it and adding a new one.

Swagger files

Swagger 2.0 files are recognized by their swagger field in the last revision. Their changelog lists the added, removed, deprecated and changed operations, by method and path like OpenAPI ones, with the rules of the commands.diff.swagger section of the configuration. Changes of the host, the base path, the schemes, the media types and the security of the whole API are metadata. A change of a path item other than of its operations, e.g. of the parameters its operations share, is shown under each of its operations. Changes of definitions, shared parameters and responses are shown under the operations using them. Files the specification references are bundled in each version, as for OpenAPI files.

apigenie changelog api/swagger.yaml --by operation --operation 'GET /pets'

AsyncAPI files

AsyncAPI 3.x files are recognized by their asyncapi field in the last revision. Their changelog lists the added, removed and changed operations, channels and servers, and the changed metadata, with the rules of the commands.diff.asyncapi section of the configuration.

An operation is shown by its action and the address of its channel, followed by its id, e.g. send user/signedup (sendUserSignedUp). Messages belong to channels, so a change of a message, e.g. of its payload, is a change of its channel, and also of the operations using the channel. Operations are identified by their id: renaming one shows as removing it and adding a new one. --operation selects operations by id, by action and address (e.g. 'send user/signedup'), or by the address of their channel:

apigenie changelog api/asyncapi.yaml --by operation --operation 'receive user/signedup'

Protobuf files

Protobuf (proto3) files are recognized by their .proto extension. Their changelog lists the added, removed and changed methods of the services, named by their service and their own name (e.g. Customers.GetCustomer), then the messages, enums, services and extended messages declared at the top level of the file, with the rules of the commands.diff.protobuf section of the configuration. A change of the package is shown like a version change (e.g. shop.v1 → shop.v2), and changes of the imports, the file options and the comment of the syntax statement as metadata.

The file is compared on its own, as by diff: the files it imports aren’t read, and the types they declare are compared by their names. So by default, only the commits changing the file are compared. A method is identified by the names of its service and its own: renaming either shows as removing the method and adding a new one. A change of a service other than of its methods, e.g. of its options, is listed under the service. --operation selects methods by their full name, by their own name or by the name of their service:

apigenie changelog api/shop.proto --by operation --operation Customers.GetCustomer

See Protobuf files of the diff command for how changes are rated.

GraphQL files

GraphQL schema files are recognized by their .graphql, .graphqls or .gql extension. Their operations are the fields of the root operation types, named by their type and their own name (e.g. Query.books or Mutation.addBook). The changelog lists the added, removed and changed operations, then the scalars, object types, interfaces, unions, enums, input objects and directive definitions of the schema, with the rules of the commands.diff.graphql section of the configuration. Changes of the root operation types, of the description of the schema and of its directives are shown as metadata. A schema has no version, so none is shown.

The file is compared on its own, as by diff: types defined in other files are compared by their names. So by default, only the commits changing the file are compared. The root operation types are those named by the schema definition, or the types named Query, Mutation and Subscription. An operation is identified by the names of its type and its field: renaming either shows as removing the operation and adding a new one. A change of a root operation type other than of its fields, e.g. of its description, is listed under the object types. --operation selects operations by their full name, by their field name, by the name of their type, or by their operation type (query, mutation or subscription):

apigenie changelog api/schema.graphql --by operation --operation Query.books

See GraphQL files of the diff command for how changes are rated.

Invalid versions

Versions that can’t be read, e.g. because of a YAML, Protobuf or GraphQL syntax error, are skipped with a warning, and the next version is compared with the last valid one.

Options

Option	Description
--revisions commits|tags	Compares every commit that changes the file (default), or every release tag.
--tag-pattern PATTERN	Glob pattern of the release tags, e.g. v*. All tags by default.
--tag-sort version|date	Orders the release tags by version numbers in their names (default), or by date.
--unreleased	With --revisions tags, adds an entry with the changes made after the last release.
--from REVISION	The revision the changelog starts after, e.g. a tag.
--to REVISION	The last revision, HEAD by default.
--path PATH	With --revisions commits, compares the commits changing these paths. Can be repeated. By default, the file and the files it references; for Protobuf and GraphQL, the file only.
--by revision|operation	Groups the changes by revision (default), or by operation (for Protobuf, by method; for GraphQL, by field of a root operation type).
--operation OPERATION	Shows the changes of an operation only: 'GET /pets', a path or an operation id (OpenAPI and Swagger); for AsyncAPI, 'send ADDRESS', a channel address or an operation id; for Protobuf, Service.Method, a method name or a service name; for GraphQL, Query.books, a field name, a root operation type name, or query, mutation or subscription. Can be repeated.
--formatter FORMATTER	stylish (default), markdown, html or json.
--config FILE	Configuration file; its diff settings (diff.swagger for Swagger, diff.asyncapi for AsyncAPI, diff.protobuf for Protobuf, diff.graphql for GraphQL) decide the severity of the changes.
--git PATH	Path to the git program.
-o, --output FILE	Writes the changelog to a file instead of printing it.

Output

The markdown formatter prints a changelog that can be published as is:

## v2.0.0 (2026-01-05)

Release 2.0 (a25ac8d, Jane Doe)

**Contains breaking changes.**

Version: 1.1.0 → 2.0.0

### Removed

- `GET /pets/{id}` (getPet) **breaking**

### Deprecated

- `GET /pets` (listPets) **breaking**

The json formatter prints the full data, including every change of the modified operations, for further processing: an object with formatVersion (the version of the format, which changes only when a member is removed or changes meaning, see Compatibility), spec, warnings, and entries (one per revision, newest first) or, with --by operation, operations (methods for Protobuf) with the history of each one. Its JSON Schema is apigenie-changelog-report.json.

{
  "formatVersion": 1,
  "spec": "petstore.yaml",
  "entries": [
    {
      "revision": { "id": "a25ac8d…", "shortId": "a25ac8d", "label": "v2.0.0", "tag": "v2.0.0", "author": "Jane Doe", "date": "2026-01-05", "subject": "Release 2.0" },
      "initial": false,
      "version": "2.0.0",
      "severity": "breaking",
      … metadata, servers, operations …
    }
  ],
  "warnings": []
}

Exit status

The command exits with 0 when it prints the changelog, even if it has breaking changes, and with 2 when git can’t be run, the file isn’t in a git repository, a revision doesn’t exist, or no revision changes the file. See the exit statuses shared by the three binaries.