---
title: "Import an OpenAPI spec"
url: "/help/buuk/import-openapi"
updated: "2026-11-13T13:32:05.033Z"
---
# Import an OpenAPI spec

The API Reference collection is generated from a spec file, not written endpoint by endpoint. Connect an OpenAPI document — YAML or JSON — and Buuk parses every operation, parameter, and response schema into ready-made reference pages with Try It panels and code examples.

In the dashboard, open **Help Centre → API Reference**. The page header says it plainly: edit the file where it lives, then sync — endpoint pages are not edited by hand here. The API Reference tab must exist first — add it with Manage tabs if it is missing (see [Documentation vs FAQ vs Guides vs API](./docs-collections)), and imports need an owner or editor role.

## Ways to get a spec in

1. **Sync from GitHub. **With the GitHub connector on ([GitHub](./github)), Buuk looks through your connected repository for spec files named `openapi.yaml`, `openapi.yml`, `openapi.json`, or the `swagger` equivalents, and imports each one it finds. The spec row keeps its repo path, so the same file on disk updates the same Buuk spec instead of piling up duplicates.
2. **Paste an upload. **If the file is not in Git yet, expand **Upload a spec instead**, paste YAML or JSON, and press **Import spec**. A successful import reports how many operations were found.

> [!TIP]
> Press **Validate** before you import. The lint report lists errors and warnings in the same panel, so you can fix the file before it becomes the live reference.

## Multiple specs per workspace

The **Connected specs** list holds one row per spec: its name from `info.title`, the version from `info.version`, where it came from (a GitHub path or Uploaded in Buuk), and the last update time.

More than one spec can live side by side — for example, a public API and an internal one, each a separate file in the repo. When there is only one spec, the public **API Reference** tab goes straight to its first operation. When there are several, readers see a picker first and choose which API to browse. Re-importing an updated file replaces the existing spec in place; removing a spec takes its pages off the site.

Uploaded specs also point the other way: the **Sync to GitHub** action writes the current spec back to your connected repository so Git can become the source of truth.

## Versions and diffs

Every sync or paste pins a snapshot of the spec. GitHub-sourced versions are labeled with a short commit hash and the commit date; uploads are labeled by date. On the public site, operation pages offer a version selector, and a reference URL can be pinned to a specific snapshot so you can link readers to the API as it was.

The **Compare with previous version** action diffs the newest snapshot against the current spec and reports breaking and non-breaking changes separately, with the details printed below the row. A breaking result is flagged so you know the change needs a closer look before readers rely on it.

## Troubleshooting

**The import fails with a parse error**

The file must be valid YAML or JSON and carry a recognized top-level key: `openapi`, `swagger`, `asyncapi`, or `openrpc`. A spec missing those keys is refused outright.

**Import succeeded but the reference looks empty**

The import only publishes what the parser found. If `paths` is empty or operations are duplicated under the same method and path (the last entry wins), the count can come back smaller than expected. Fix the spec and re-import — the new snapshot replaces the old.

**Validate reports warnings**

Warnings do not block the import; errors do. Clear the errors, skim the warnings — usually missing descriptions or examples — and import when the report is clean enough for your team.

**The import button refuses with reference disabled**

Add the API Reference tab with Manage tabs in **Help Centre**, then try again. Empty collections hide their public tab, so nothing shows until a spec is connected anyway.

## Related

- Send a real request from an operation: [The Try It playground](./try-it-playground).
- Exports per spec: [Code samples and SDKs](./code-samples-and-sdks).
- Spec types beyond plain REST: [Other reference types](./other-reference-types).
- Keeping the collection visible: [Documentation vs FAQ vs Guides vs API](./docs-collections).
- The connector behind repo sync: [GitHub](./github).