What is Swagger? OpenAPI Specification, Tools, Examples

What is Swagger?

Swagger is an ecosystem of open-source tools built around the OpenAPI Specification (OAS) for designing, documenting, and consuming REST APIs. Originally developed by SmartBear, the spec was donated to the Linux Foundation in 2016 and rebranded as OpenAPI — but the Swagger name stuck for the tooling (Swagger UI, Swagger Editor, Swagger Codegen, Swagger Hub).

The OpenAPI Specification (currently 3.1) is a YAML or JSON document that describes a REST API: endpoints, parameters, request/response schemas, authentication, examples. Tools then generate documentation, client SDKs, server stubs, mock servers, and tests from this spec.

Swagger vs OpenAPI: what's the difference?

Anatomy of an OpenAPI spec

openapi: 3.1.0
info:
  title: Pet Store API
  version: 1.0.0
  description: A simple pet store
servers:
  - url: https://api.petstore.example.com/v1
paths:
  /pets:
    get:
      summary: List all pets
      parameters:
        - name: limit
          in: query
          schema:
            type: integer
      responses:
        '200':
          description: A paged list of pets
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Pet'
components:
  schemas:
    Pet:
      type: object
      required: [id, name]
      properties:
        id:
          type: integer
        name:
          type: string

That spec generates: interactive docs (try-it-out), TypeScript client, Java server stub, mock server, contract tests — all from one source of truth.

Swagger ecosystem tools

Why use Swagger / OpenAPI?

• Single source of truth. The spec is the contract. Docs, code, tests all derive from it.
• Design-first APIs. Write the spec before writing code; review with stakeholders early.
• Auto-generated client SDKs. Don't hand-write HTTP clients in 8 languages; generate them.
• Interactive docs. Swagger UI's "Try it out" lets users test endpoints from the browser.
• Mock servers. Frontend can develop against a mock derived from the spec while backend is in progress.
• Contract testing. Verify your real API matches the spec; catch drift in CI.
• Standardized format. 1000s of tools support OpenAPI; widely understood.
• Code-first or design-first. Generate spec from code (annotations) OR generate code from spec.

OpenAPI 3.0 vs 3.1: what changed?

Common OpenAPI workflows

Design-first (recommended)

1. Write the OpenAPI spec collaboratively (in Swagger Editor, Stoplight, or VSCode).
2. Review with stakeholders.
3. Generate server stubs + client SDKs.
4. Implement business logic in stubs.
5. Use spec for contract tests in CI.

Code-first

1. Annotate code with framework-specific decorators (Spring SpringDoc, FastAPI, NestJS, etc.).
2. Framework auto-generates OpenAPI spec at build time or runtime.
3. Spec served at /swagger.json or /openapi.json.
4. Swagger UI renders interactive docs.

Code-first is faster initially; design-first scales better for large teams and stable APIs.

Pitfalls and best practices

• Spec drift from reality. Code-first usually safe; design-first needs tests verifying real API matches spec. Use Dredd or Schemathesis.
• Missing examples. Specs without example values are hard to use. Add example to each schema.
• Inconsistent naming. Use Spectral to enforce style (camelCase vs snake_case, plural vs singular paths).
• Over-deep nesting. Specs become unreadable. Use $ref + components heavily.
• Auth misdocumented. Define security schemes properly so SDKs handle auth correctly.
• Ignored versioning. Use info.version; bump on breaking changes; consider /v1/, /v2/ in paths.

FAQ: Swagger / OpenAPI

Is Swagger free?

The open-source tools (UI, Editor, Codegen) are free. Swagger Hub (commercial) has a free tier and paid plans.

Should I use Swagger or Postman?

Different purposes. Swagger/OpenAPI is the spec format; Postman is for testing/exploring. They complement each other — Postman can import OpenAPI specs.

Should I use design-first or code-first?

Design-first for stable, public APIs and large teams. Code-first for internal/iterating-fast APIs. Many start code-first, switch to design-first as APIs mature.

What replaces Swagger Codegen?

OpenAPI Generator — a community fork with more active development, more languages, fewer bugs.

Can I use Swagger for GraphQL or gRPC?

No — OpenAPI is REST-specific. GraphQL has its own schema (SDL). gRPC uses Protocol Buffers.

How do I version my API?

Two approaches: URL versioning (/v1/users) or header versioning (Accept: application/vnd.example.v1+json). URL versioning is simpler and Swagger UI handles it well.

What's the difference between Swagger UI and Redoc?

Both render OpenAPI specs as docs. Swagger UI: interactive (try-it-out). Redoc: cleaner three-pane layout, no try-it-out by default. Some teams use both — Swagger UI for dev, Redoc for public docs.

Load test your Swagger-documented API with LoadFocus

If you have an OpenAPI spec and want to load test the implementation, LoadFocus runs JMeter and k6 scripts against your real API from 25+ regions with up to 12,500 VUs. Sign up free at loadfocus.com/signup.