On this page
  1. What is OpenAPI?
  2. What is OpenAPI used for?
  3. How do you use OpenAPI in practice?
  4. When should you skip OpenAPI?
  5. Where AI coding assistants get this wrong
  6. Checklist
  7. FAQ
    1. What is OpenAPI in simple terms?
    2. Is Swagger the same as OpenAPI?
    3. Do I need an OpenAPI spec for a small app?
    4. Does OpenAPI replace REST?
    5. Is OpenAPI only for documentation?
    6. How do I keep an OpenAPI spec accurate?
  8. Related topics
  9. Sources
concept

What Is OpenAPI (and Do You Need It)?

OpenAPI is a machine-readable description of your API. Learn what it is, what it is not, and whether a small app should bother with a spec.

Software Engineeringbeginner7 min readUpdated 2026-09-29

Quick answer

  • OpenAPI is a machine-readable description of an HTTP API: its paths, parameters, request bodies, and responses, written in YAML or JSON.
  • Software reads it to generate interactive docs, typed client libraries, mock servers, and contract tests.
  • The spec is not Swagger UI, and it is not documentation prose — it is a structured contract.
  • For a small app, generate it from your code. Write it by hand only when the spec is meant to drive multiple clients.

What is OpenAPI?

OpenAPI is an industry-standard specification for describing HTTP APIs. An OpenAPI document is a YAML or JSON file that lists every endpoint in your API, the parameters and body each one accepts, the responses it can return, and how requests are authenticated — in a structured form that software can read, not just humans.

Because it is machine-readable, a single file can feed several tools at once: Swagger UI renders it as interactive documentation, generators produce typed client libraries in any language, mock servers can stand in for the real API before it exists, and test harnesses can check that your implementation still matches the spec.

The current version is OpenAPI 3.x, maintained by the Linux Foundation’s OpenAPI Initiative.

Where this bites vibecoders

The specific way this bites vibecoders is a spec that describes an API nobody has. An assistant asked to “add OpenAPI docs” will sometimes write a hand-authored spec file describing a clean, well-named API — and your actual routes are get_user_v2 and /api/thing/final. The document is worse than useless because it looks authoritative, and the mismatch only surfaces when someone generates a client from it and calls endpoints that return 404. Generating the spec from the real routes avoids this entirely.

What is OpenAPI used for?

Five concrete uses, in rough order of how often they matter for a small team:

Interactive documentation. Swagger UI reads the spec and renders browsable documentation with a “try it” button, so a consumer can see every endpoint and try a real request without writing code.

Client generation. Point a generator at the spec and receive a typed client in Python, TypeScript, Go, or Java, with request and response types already correct. This removes a whole category of manual mistakes.

Mock servers. With a spec, a tool can serve realistic fake responses before the backend exists. Frontend and backend can be built in parallel against the same contract.

Contract testing. Check in CI that your running API still matches the spec. This catches the common failure where a response field was renamed and a client’s types silently went stale.

Tooling and gateways. API gateways, mock services, documentation sites, and SDK generators all consume OpenAPI as their common input.

How do you use OpenAPI in practice?

There are two workflows, and picking the right one is most of the decision.

Code first, then generate the spec. You write routes as normal, and a tool inspects the code and emits a spec. This is right for most applications. The spec is guaranteed to match reality because it is derived from it, and you get documentation nearly free.

Spec first, then generate scaffolding. You write the spec as the contract, and tools generate route stubs, models, and clients. This is the contract-first approach, and it earns its cost when several consumers depend on the API: multiple teams, multiple client languages, or an SDK you ship to third parties. The trade-off is real — a spec nobody keeps in sync becomes a lie, and keeping it in sync is work.

A third, very common option is no spec at all for a private, single-consumer API. If only your own frontend calls your own backend, a hand-written spec is ceremony. Generating one for documentation is still worthwhile because it is nearly free.

A minimal spec looks like this:

openapi: 3.0.3
info:
  title: Orders API
  version: 1.0.0
paths:
  /orders/{id}:
    get:
      summary: Fetch a single order
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: The order
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Order"
        "404":
          description: No order with that id
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
  schemas:
    Order:
      type: object
      required: [id, total]
      properties:
        id:
          type: string
        total:
          type: number

When should you skip OpenAPI?

A spec is not automatically worth the maintenance. Skip it, or generate it only for docs, when:

  • You have one internal consumer — your own frontend calling your own backend.
  • The API is still changing shape weekly and the spec would be rewritten constantly.
  • Nobody will read it — a spec no consumer and no tool uses is pure overhead.
  • You are not prepared to keep it accurate. A stale spec is worse than none, because it is trusted.

Do add one when you ship an SDK, when a partner integrates with you, when you want typed clients in a second language, or when contract testing in CI is worth the setup.

Where AI coding assistants get this wrong

  • Hand-writing a spec that does not match the actual routes, producing authoritative-looking documentation for an API that does not exist.
  • Inventing endpoints, fields, and response shapes rather than reading the code that exists, so the document is fiction.
  • Not using $ref for repeated schemas, duplicating an Order object in twelve places so a rename has to be applied everywhere.
  • Omitting the security scheme, so the spec describes an API that appears to require no authentication.
  • Confusing Swagger UI with OpenAPI, treating “add Swagger” as a request for interactive docs while never producing a spec.
  • Documenting only the happy path — no error responses, no required/optional distinction, no pagination parameters.
  • Letting the spec drift, because nothing checks the running API against it in CI.

Checklist

  • Generate the spec from your code by default; hand-write it only for a contract-first design.
  • Keep the generated spec under version control alongside the routes.
  • Use $ref and components for any schema used more than once.
  • Document error responses, not just the success case.
  • Mark parameters as required and describe types precisely.
  • Include the authentication scheme so consumers know how to authenticate.
  • Render it with Swagger UI for browsable documentation.
  • Add a CI check that the running API still matches the spec.
  • Skip the spec entirely for a single-consumer internal API.
  • Regenerate rather than hand-editing generated output.

FAQ

What is OpenAPI in simple terms?

OpenAPI is a standard file format — usually YAML or JSON — that describes an HTTP API’s endpoints, the parameters they accept, and the responses they return, in a way that software can read. Tools use it to generate documentation, client libraries, and mock servers, and to check that your code still matches the contract.

Is Swagger the same as OpenAPI?

Not any more. Swagger originally referred both to the specification and to a toolset from SmartBear. The specification was renamed to OpenAPI and is now maintained by the Linux Foundation, while “Swagger” usually means the ecosystem of tooling around it, including Swagger UI, which renders an OpenAPI file as interactive documentation.

Do I need an OpenAPI spec for a small app?

Usually not as a hand-written document. Most frameworks can generate a spec from your code, which gives you documentation and type-safe clients for almost no effort. Writing the spec first as the contract is worth it when more than one team consumes the API, or when you want the contract to drive code generation in several languages.

Does OpenAPI replace REST?

No, and it is not comparable to REST. REST is an architectural style — a set of constraints for designing networked applications. OpenAPI is a description format for HTTP APIs, and you can describe a REST API with it, though it also works for non-REST HTTP APIs. If you are choosing an API style, that is a different decision — see REST vs GraphQL vs gRPC.

Is OpenAPI only for documentation?

No, documentation is the most visible use but not the most valuable one. The spec also drives client generation, mock servers, and contract tests, which is where it pays back — because a machine-readable contract catches drift that prose documentation never would.

How do I keep an OpenAPI spec accurate?

Generate it from the code, and commit the output. If you hand-write the spec, add a CI step that starts the app and compares its real routes and schemas against the document, failing the build on drift. A spec that is never checked against reality will eventually describe an API you no longer have.

Sources

Share: