OpenAPI vs Swagger: What's the Difference?

The short answer:

• OpenAPI is a specification — a standard format (YAML or JSON) for describing an HTTP API: its endpoints, parameters, request and response shapes, authentication.
• Swagger is the original name of that specification (up to version 2.0) and today the brand of a set of tools built around it — Swagger UI, Swagger Editor, Swagger Codegen.

In 2015 the Swagger specification was donated to the Linux Foundation and renamed OpenAPI. Version 3.0 onwards is "OpenAPI". People still say "Swagger docs" to mean interactive API documentation generated from an OpenAPI file.

What an OpenAPI document looks like

openapi: 3.1.0
info:
  title: Invoices API
  version: 1.0.0
paths:
  /v1/invoices/{id}:
    get:
      summary: Get an invoice
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: The invoice
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Invoice' }
        '404':
          description: Not found
components:
  schemas:
    Invoice:
      type: object
      required: [id, amount, status]
      properties:
        id: { type: string }
        amount: { type: number }
        status: { type: string, enum: [draft, sent, paid] }
  securitySchemes:
    bearer: { type: http, scheme: bearer }
security:
  - bearer: []

OpenAPI 3.1 uses standard JSON Schema for data shapes. (What is YAML?, What is JSON?)

What you get from it

• Interactive docs — Swagger UI, Redoc, Scalar render the file as browsable documentation with "try it" buttons.
• Client SDKs and types — generate TypeScript types or a full client (openapi-typescript, openapi-generator), so your front end or customers' code stays in sync. (tRPC vs REST)
• Validation — reject requests that don't match the spec.
• Mock servers — front-end work can start before the back end exists.
• Contract testing and breaking-change detection in CI. (API versioning)
• Import into API clients like Postman or Bruno. (How to test an API)
• AI tools — agents and LLM function-calling setups can read an OpenAPI spec to understand how to call your API. (MCP vs API)

Code-first vs design-first

Code-first: write the API, generate the spec from the code.

• FastAPI does this automatically — your app serves /openapi.json and /docs. (What is FastAPI?)
• In Node, libraries like Zod-to-OpenAPI, Hono's OpenAPI middleware, or NestJS's decorators generate it from your schemas.

Design-first: write the spec, review it, then implement (and generate stubs).

• Better when several teams or external partners must agree on the contract before building.

Small teams usually go code-first. What matters is that the spec stays accurate — generated specs drift less than hand-maintained ones.

Swagger tools today

Tool	Does
Swagger UI	Interactive docs from a spec
Swagger Editor	Edit a spec with live preview and validation
Swagger Codegen	Generate clients/servers (the community fork openapi-generator is more active)

Plenty of non-Swagger tools use the same spec: Redoc, Scalar, Stoplight, Spectral (linting).

Tips

• Describe errors, not just success responses.
• Add examples — they make docs and AI tool use much better.
• Lint the spec (Spectral) for consistency: naming, required descriptions.
• Don't expose internal endpoints in a public spec.
• Protect the docs page if the API is private.

---

EasySpawn serves your API and its docs from your own server behind HTTPS, and Claude Code can generate or update the OpenAPI spec as the API changes. See how it works or join the waitlist.

Related: Designing a REST API · API Versioning · What Is FastAPI? · How to Test an API