# Quickstart

Source: https://apigenie.pl/docs/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:

```sh
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:

```sh
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`):

```sh
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:

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

### Linux packages

[Downloads](/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`:

```sh
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:

```sh
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](/downloads), extract it, and add the folder to
the `PATH`: it holds `apigenie.exe` and the other executables. Then, in a new terminal:

```powershell
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:

```yaml
- 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](/docs/ci/github-action)). The other CI systems install with npm or the archive
([CI](/docs/ci)).

The editor runs in the browser with nothing to install: [open it](/tools/editor) on a folder of your API files.

## Pick your starting point

- [I have an API](#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](#im-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](#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](/docs/linter/openapi) until you configure another.

```sh
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.

```sh
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.

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

To run both on every pull request, add the [GitHub Action](/docs/ci/github-action) to
`.github/workflows/api.yaml`. It shows the issues and the breaking changes on the lines of the pull request.

```yaml
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.

```sh
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:

```yaml
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.

```sh
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.

```sh
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](/docs/reference/generator) also writes Java, Go, Python, C# and Elixir.

```sh
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.

```sh
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
# 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.

```sh
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`.

```sh
apigenie-catalog list
apigenie-catalog init
```

The [linter rules](/docs/linter) list every rule and ruleset; your own rules are written like
[Spectral rules](/docs/reference/cli/lint#custom-rules).

## Next steps

- [Configuration](/docs/reference/cli/configuration): every setting of `apigenie.yaml`.
- [`apigenie`](/docs/reference/cli): every command and option.
- [`apigenie-server`](/docs/reference/server): stubs, scenarios, the dashboard and record and replay.
- [Changelog](/changelog): what changed in each release.
