Get startedQuickstart

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 four command-line tools: apigenie, apigenie-generator,apigenie-server and apigenie-catalog. With Homebrew on macOS and Linux:

$ brew install mykulyak/apigenie/apigenie
$ apigenie --version

Or with npm, anywhere Node.js runs:

$ npm install -g @mykulyak/api-genie

Downloads has Docker, the Linux packages and the archives for Windows. 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

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