GitHub Action

The API Genie GitHub Action installs the CLI on GitHub Actions runners and lints, checks the formatting of, or diffs OpenAPI, Swagger 2.0, AsyncAPI, Protobuf and GraphQL files. Issues and changes are shown as annotations on the files of a pull request, and a report is added to the job summary. The action is published on the GitHub Marketplace as mykulyak/api-genie-action; its source and its releases are in mykulyak/api-genie-action.

Usage

on: pull_request
jobs:
  api:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: mykulyak/api-genie-action@v0
        with:
          command: lint
          files: api/**/*.yaml
          config: apigenie.yaml
      - uses: mykulyak/api-genie-action@v0
        with:
          command: format
          files: api/**/*.yaml
      - uses: mykulyak/api-genie-action@v0
        with:
          command: diff
          files: api/openapi.yaml

• lint fails the step when an issue of severity error is reported (see lint).
• format runs apigenie format --check: nothing is written, and the step fails when a file is not formatted.
• diff compares each file with its version at the base commit of the pull request, or the commit before a push, and fails the step on breaking changes. Set base to compare with another commit, branch or tag, or base-file to compare two files of the repository.
• Without command, the action only installs apigenie and puts it on PATH, for the steps that follow.

Inputs

Input	Description
version	CLI version: latest (default), X.Y.Z or cli-X.Y.Z. 0.9.0 is the oldest supported version.
command	lint, format or diff.
files	Files, one per line or separated by spaces. Glob patterns such as api/**/*.yaml are expanded.
config	The configuration file.
formatter	Formatter of lint and diff. Only the default, unix, becomes annotations.
report	Report of diff: status, changelog (default) or detailed.
fail-on	error (default), warning (lint warnings fail the step too) or never.
base, base-file	What diff compares with.
args	More arguments for the command, separated by spaces.
annotations, summary	Turn the annotations or the job summary off with false.

Outputs

Output	Description
status	lint: clean, warnings or errors. format: clean or changed. diff: none, non-breaking or breaking.
exit-code	The exit status of the CLI.
error-count, warning-count	The numbers of lint errors and warnings.
changed-files	The files that are not formatted.
version, path	The installed CLI and its location.

Runners

The action runs on Linux x64, macOS arm64 and Windows x64 runners. It downloads the CLI from the GitHub release, checks it against the release’s checksums, and reuses it in later steps of the same job.