What Is OpenAPI

An OpenAPI document is a single file that describes exactly how an API works — every endpoint, every parameter, every response, and how to authenticate. It is the contract your tools, your teammates, and your pipeline all read from. If you have ever wanted one source of truth for an API instead of a stale wiki page and a folder of saved requests, OpenAPI is that source of truth.

This guide explains what OpenAPI is, what lives inside a spec, how it differs from Swagger, what changed across versions, and how to actually work with it day to day — then shows where Atrahasis fits in.

What Is OpenAPI?

OpenAPI is a standard, machine-readable format for describing REST APIs. A single OpenAPI document — written in YAML or JSON — defines an API's endpoints, the parameters and request bodies they accept, the responses they return, and the security schemes that protect them.

Because the format is standardized, any tool that understands OpenAPI can read your API the same way: documentation generators, code generators, mock servers, contract testers, and API clients all consume the same file. You describe the API once, and the whole ecosystem understands it.

That is the core idea: the spec is the contract. Everyone — frontend, backend, QA, and your CI pipeline — agrees on the same description before a single line of production code ships.

What's Inside an OpenAPI Document

An OpenAPI document is structured into a few top-level sections:

info — the API's title, version, and description.g
servers — the base URLs the API lives at, often one per environment (dev, staging, prod).
paths — every endpoint, grouped by URL, with the HTTP methods each one supports (GET, POST, PUT, PATCH, DELETE).
parameters — query, path, header, and cookie inputs each operation accepts.
requestBody — the data an endpoint expects, usually JSON described by a schema.
responses — what comes back for each status code, again described by schemas.
components — reusable building blocks: shared schemas, securitySchemes, parameters, and responses you reference instead of repeating.
security — which authentication methods apply, globally or per operation.

Schemas are where most of the value lives. They describe the exact shape of your data — field names, types, required fields, formats, and enums — using JSON Schema. A well-written schema means a consumer knows precisely what a request and response look like without trial and error.

OpenAPI vs. Swagger

The two terms cause endless confusion, so here is the short version:

Swagger was the original name of the specification. In 2015 the spec was donated to the OpenAPI Initiative and renamed OpenAPI. So "Swagger 2.0" and "OpenAPI 2.0" are the same thing.

Today, OpenAPI refers to the specification, and Swagger refers to a set of tools (Swagger UI, Swagger Editor, Swagger Codegen) built around it. If someone says "the Swagger file," they almost always mean the OpenAPI document.

Why OpenAPI Matters

Describing an API in a standard format unlocks a lot for free:

Documentation — generate always-current, interactive docs straight from the spec instead of hand-writing them.
Code generation — produce client SDKs and server stubs in many languages from one file.
Mocking — stand up a fake API from the spec before the real backend exists, so frontend work isn't blocked.
Contract testing — verify that real responses still match the agreed shape, and catch breaking changes before they reach a consumer.
Governance — lint specs for consistency, enforce naming and security rules across teams.

In short, OpenAPI turns "the API" from tribal knowledge into a versioned artifact you can review, diff, and automate.

OpenAPI Versions, Briefly

You'll run into a few versions in the wild:

Swagger 2.0 — the widely deployed predecessor. Still common in older systems.
OpenAPI 3.0 — a major redesign: cleaner request bodies, reusable components, richer security, and content negotiation.
OpenAPI 3.1 — aligns fully with JSON Schema 2020-12 and adds webhooks. The current sweet spot for new APIs.
OpenAPI 3.2 — the latest revision, refining the 3.x line.

The practical takeaway: new APIs should target 3.1, but you'll inevitably inherit 2.0 and 3.0 specs — so the tools you choose need to read and convert all of them.

Design-First vs. Code-First

There are two common ways teams produce a spec:

Design-first — write the OpenAPI document before building the API. The spec drives the implementation and gives every team a contract to work against from day one.
Code-first — generate the spec from annotations in your backend code. Faster to start, but the spec is only as accurate as the code it's derived from.

Both are valid. What matters is that the spec stays accurate — a document that drifts out of sync with the real API is worse than no document at all, because people trust it and get burned.

Atrahasis: OpenAPI as a First-Class Citizen

Most tools treat OpenAPI as an import/export afterthought — you bring a spec in, it becomes a flat list of requests, and the connection to the original document is lost. Atrahasis takes the opposite approach: your project is the OpenAPI spec, and that makes everything downstream simpler.

The spec and your work never drift

Every change you make — in the visual designer, in the raw code, or by adding an endpoint — flows back into the OpenAPI document automatically. Edit the YAML and the project updates; edit the project and the YAML updates. When both sides change, built-in conflict resolution (source-wins, target-wins, deep-merge, or ask) keeps them reconciled. There is no "export and hope" step.

Visual designer and code editor, same document

Build specs with form-based editors for Info, Servers, Tags, Paths, Parameters, Schemas, Security Schemes, Webhooks, and Callbacks — guided fields that never produce invalid output. Prefer raw editing? Switch to the code editor with live validation and a Swagger UI-style preview that updates as you type. Design, Split, and Preview modes show the same spec from different angles, always in sync.

Every version, read and converted

Swagger 2.0 specs auto-upgrade to OpenAPI 3.0.3 on import. 3.0 and 3.1 convert in both directions. 3.2 is supported for reading and editing. Whether a spec is twelve years old or shipped last quarter, Atrahasis reads it, edits it, and exports clean, standard OpenAPI as YAML or JSON — no proprietary format, no lock-in.

The hard parts, not skipped

Atrahasis handles the OpenAPI features most tools quietly drop:

Full JSON Schema 2020-12 with schema composition — allOf, oneOf, anyOf, and discriminator for inheritance and polymorphism.
$ref resolution — internal, external file, and URL references, circular-reference safe.
All seven parameter serialization styles, plus server variables and operation-level overrides.
Webhooks (3.1+) and callbacks (3.0+) with runtime expressions.
Every security scheme — API Key, Basic, Bearer, OAuth 2.0 (all four flows, with PKCE), and OpenID Connect via discovery URL.

Design and test in one place

You don't have to leave the designer to try an endpoint. Area mode opens your endpoints in tabs with the full request panel — params, headers, auth, body, assertions — so you edit the spec and test the call without switching tools. Try It Out adds smart example generation, environment variables in parameters, per-operation lock icons, automatic token refresh, and one-click export of any request as an atra CLI command. Meanwhile, every response is checked against your schema automatically, with pass/fail shown in the Contract tab.

Your spec stays yours

Atrahasis stores its own metadata as standard x-atrahasis-* extensions that other tools simply ignore, and it preserves unknown x-* extensions from other tools too. Industry standards in, industry standards out — bring an existing spec and pick up where another tool left off, or design from scratch and export anywhere.

Conclusion

OpenAPI is the standard way to describe a REST API in a single, machine-readable file — the contract your docs, codegen, mocks, tests, and pipelines all share. Understanding what's inside a spec, how the versions differ, and the difference between OpenAPI and Swagger is enough to start working with it confidently.