Quickstart

Install the tools, pick where you are starting from, and run your first commands. Each path takes about five minutes, with an OpenAPI file of your own or the example below.

Install

One package installs the five command-line tools: apigenie, apigenie-generator, apigenie-server, apigenie-catalog and apigenie-mcp. Pick the channel that fits where you work; apigenie --version prints the version of all five.

Homebrew

On macOS and Linux:

brew install mykulyak/apigenie/apigenie
apigenie --version

npm

Anywhere Node.js 18 or later runs, Windows included. The package downloads the binaries of your platform:

npm install -g @mykulyak/api-genie
apigenie --version

npx @mykulyak/api-genie --version runs the CLI without a global install.

Docker

Two images, built for linux/amd64, work in /mnt/data, so mount the directory of your files there. mykulyak/apigenie runs apigenie and holds apigenie-generator (--entrypoint apigenie-generator):

docker run --rm -v "$PWD:/mnt/data" mykulyak/apigenie lint openapi.yaml

mykulyak/apigenie-server runs the mock, listening on every interface of the container, on port 4010:

docker run --rm -p 4010:4010 -v "$PWD:/mnt/data" mykulyak/apigenie-server openapi.yaml

Linux packages

Downloads has a .deb, an .rpm and a .tar.gz for x64 Linux, each with a .sha256 file next to it. The packages put the tools in /usr/bin:

sudo dpkg -i apigenie-<version>-linux-x64.deb   # Debian and Ubuntu
sudo rpm -i apigenie-<version>-linux-x64.rpm    # Fedora and RHEL

The archive holds the executables without a directory, so extract it where you keep binaries:

sha256sum -c apigenie-<version>-linux-x64.tar.gz.sha256
sudo tar -xzf apigenie-<version>-linux-x64.tar.gz -C /usr/local/bin

Windows

Download apigenie-<version>-windows-x64.zip from Downloads, extract it, and add the folder to the PATH: it holds apigenie.exe and the other executables. Then, in a new terminal:

apigenie --version

npm works on Windows too.

GitHub Action

A step with mykulyak/api-genie-action@v0 and no command installs apigenie on the runner and puts it on the PATH for the steps after it; version pins a release:

- uses: mykulyak/api-genie-action@v0
- run: apigenie lint openapi.yaml

With command, the step runs lint, format or diff itself and annotates the pull request (GitHub Action). The other CI systems install with npm or the archive (CI).

The editor runs in the browser with nothing to install: open it on a folder of your API files.

Pick your starting point

  • I have an API: check the description you have, catch breaking changes in pull requests, and publish its documentation.
  • I’m building a new API: write the contract first, mock it for the client teams, and generate the code of both sides.
  • I need my APIs consistent: give every API of the organization the same rules and style, and know what APIs there are.

I have an API

Start with what the linter says about your description. It reads OpenAPI, Swagger 2.0, AsyncAPI, Protobuf and GraphQL files, and applies the recommended ruleset until you configure another.

apigenie lint openapi.yaml

Every issue names its line and its rule, and each rule has a page that says why it matters. --fix fixes the issues that have a safe fix. Then put the file in a consistent style; --check only reports the files it would change.

apigenie format openapi.yaml

Before the next change ships, compare it with the version on the main branch. The command exits with status 1 when a change breaks clients.

git show main:openapi.yaml > main.yaml
apigenie diff main.yaml openapi.yaml

To run both on every pull request, add the GitHub Action to .github/workflows/api.yaml. It shows the issues and the breaking changes on the lines of the pull request.

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

Finally, a documentation site, with search and Try it out, from the same file. Serve docs/dist from any static host.

apigenie-generator docs openapi.yaml -o docs
cd docs && npm install && npm run build

I’m building a new API

Describe the API before writing its code. Save this as openapi.yaml, or start from a file of your own:

openapi: 3.1.0
info:
  title: Notes API
  version: 0.1.0
servers:
  - url: http://localhost:4010
paths:
  /notes:
    get:
      operationId: listNotes
      summary: List the notes
      responses:
        "200":
          description: The notes
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Note"
components:
  schemas:
    Note:
      type: object
      required: [id, text]
      properties:
        id:
          type: integer
          format: int64
        text:
          type: string
          maxLength: 500

Lint it as you write it: the linter knows what a good contract needs, such as descriptions and limits.

apigenie lint openapi.yaml

Serve it as a mock, so that client teams can start now. --dynamic generates every answer from the schemas; without it, the mock answers with the document’s examples first.

apigenie-server openapi.yaml --dynamic
curl http://127.0.0.1:4010/notes

Generate a TypeScript client and an Express server from the same contract. The generator also writes Java, Go, Python, C# and Elixir.

apigenie-generator client fetch openapi.yaml -o client
apigenie-generator server express openapi.yaml -o server

Once the real server runs, put the mock in front of it as a validating proxy. Your tests then check that the server keeps the contract.

apigenie-server openapi.yaml --proxy-to http://localhost:8080 --report contract.json --fail-on errors

I need my APIs consistent

Put the rules in an apigenie.yaml at the root of the repository. Every command finds it, and editors that read the schema comment complete and check it.

# yaml-language-server: $schema=https://apigenie.pl/schemas/apigenie-config/latest.json
version: '1.0'
commands:
  lint:
    extends: [recommended]
    rules:
      tags-unique: error

Lint and format every API of the repository with the same rules and the same style, whatever its standard.

apigenie lint apis/*.yaml proto/*.proto
apigenie format apis/*.yaml proto/*.proto

List the APIs of the repository, then record their names and owners in the same apigenie.yaml.

apigenie-catalog list
apigenie-catalog init

The linter rules list every rule and ruleset; your own rules are written like Spectral rules.

Next steps

Was this helpful?