OpenAPI Source

Apistaq needs a single, authoritative OpenAPI spec. This guide covers the three ways to supply it and best practices for each.

GitHub / GitLab / Bitbucket

Authorize the Apistaq GitHub (or GitLab / Bitbucket) app on your account or organization. Then select:

  • Repository — the repo where your OpenAPI spec lives
  • Branch — typically main or a dedicated api-spec branch
  • File path — relative path to your spec file, e.g. openapi/spec.yaml

Apistaq installs a webhook and syncs on every push to the configured branch. Only the spec file itself is read — Apistaq does not access your source code.

Branch strategy tip: Point Apistaq at your release branch, not develop or main if those branches receive unreviewed changes. Breaking-change detection runs on every sync, so it's best to gate syncs on reviewed merges.

Direct URL

If your OpenAPI spec is published as a public or authenticated URL (e.g. served by your API gateway at /openapi.yaml), you can use the Direct URL source type.

Configure a sync interval: every push (via webhook), every 15 minutes, hourly, or daily. For production specs that don't change frequently, daily is fine.

Manual upload

Upload a .yaml or .json file from your machine. Manual uploads are useful for testing a new project before connecting a git source. Syncs only happen when you re-upload.

Spec validation

On every sync, Apistaq validates your spec against OpenAPI 3.0 and 3.1. Validation warnings (not errors) are displayed in the sync log but do not block SDK generation. Errors (e.g., malformed YAML, missing info.version) will fail the sync and notify you.