OpenAPI and Swagger Documentation Guide — Define, Document, and Test APIs

What Is OpenAPI (Swagger)?

OpenAPI Specification (OAS) is a language-agnostic standard for describing HTTP APIs. Originally known as Swagger (and still commonly referred to as such), OpenAPI 3.x is the current standard maintained by the OpenAPI Initiative. An OpenAPI document is a JSON or YAML file that fully describes your API's endpoints, request/response schemas, authentication methods, and more.

Swagger remains the name of the toolset — Swagger Editor, Swagger UI, Swagger Codegen — while OpenAPI is the specification. In 2026, OpenAPI 3.1 (aligned with JSON Schema) is the recommended version.

How to Write an OpenAPI Specification

1. Start with the info block — API title, version, and description.
2. Define servers — base URL(s) for your API.
3. Add paths — each endpoint with its HTTP methods, parameters, and responses.
4. Define schemas — reusable component schemas for request/response bodies.
5. Add security definitions — API key, Bearer token, or OAuth 2.0.
6. Validate your spec — use the Swagger Editor or a validator CLI.

Key Features of OpenAPI

• Interactive documentation — Swagger UI renders your spec as a beautiful, testable API explorer.
• Code generation — Generate client SDKs in 50+ languages from your spec using OpenAPI Generator.
• Request validation — Libraries like express-openapi-validator validate incoming requests against your spec automatically.
• Mock servers — Tools like Prism generate a mock server from your spec before backend is implemented.
• Type generation — Generate TypeScript types from your OpenAPI spec with openapi-typescript.
• Contract testing — Validate that your implementation matches your spec using Dredd or Schemathesis.

Sample OpenAPI 3.1 Snippet

openapi: 3.1.0
info:
  title: Users API
  version: 1.0.0
paths:
  /users:
    get:
      summary: List all users
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'
components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: integer
        email:
          type: string
          format: email

Use Cases

API-First Development

Design the OpenAPI spec before writing code. Use Prism to generate a mock server. Frontend and backend teams work in parallel against the agreed spec. This eliminates integration surprises and shortens development cycles.

Auto-Generating SDKs

Large API providers (Stripe, Twilio, AWS) maintain their OpenAPI specs and automatically generate client libraries for a dozen languages. Every time the API changes, updated SDKs are generated and published, dramatically reducing manual SDK maintenance.

Frequently Asked Questions

What is the difference between OpenAPI 2.0 and 3.0?

OpenAPI 2.0 (Swagger 2.0) uses a different structure with separate definitions, parameters, and responses sections. OpenAPI 3.0 consolidated these under components, added support for multiple servers, and improved schema handling. OpenAPI 3.1 further aligned with JSON Schema 2020-12. Migrate to 3.1 for new projects.

Should I write OpenAPI in JSON or YAML?

YAML is more readable for humans and the preferred format for most teams. JSON is better when the spec is generated programmatically. Both are valid — many tools accept either. Stick to one format within a project for consistency.

How do I add authentication to an OpenAPI spec?

Define security schemes in components/securitySchemes (e.g., bearerAuth for JWT), then reference them in individual operations or globally with a top-level security field. Tools like Swagger UI will include the auth fields in the interactive tester.

What is the difference between Swagger Editor and Swagger UI?

Swagger Editor is a browser-based tool for writing and validating OpenAPI specs with real-time error checking. Swagger UI renders a spec as interactive HTML documentation where users can test endpoints directly. Both are open source and can be self-hosted.

Can OpenAPI describe WebSocket APIs?

Standard OpenAPI (HTTP-based) doesn't describe WebSocket or event-driven APIs. For those, AsyncAPI is the equivalent specification standard. OpenAPI focuses on synchronous HTTP request-response patterns.