Swagger OpenAPI 2.0 is a surprisingly rigid specification that, when followed, unlocks massive developer productivity.
Let’s watch a minimal OpenAPI 2.0 spec come to life. Imagine we’re building a simple API to manage user profiles.
swagger: "2.0"
info:
version: "1.0.0"
title: "User Profile API"
host: "api.example.com"
basePath: "/v1"
schemes:
- "https"
paths:
/users/{userId}:
get:
summary: "Get a user profile by ID"
parameters:
- name: userId
in: path
required: true
type: string
description: "The ID of the user to retrieve."
responses:
"200":
description: "User profile found"
schema:
$ref: "#/definitions/User"
"404":
description: "User not found"
definitions:
User:
type: object
properties:
id:
type: string
name:
type: string
email:
type: string
required:
- id
- name
- email
This spec defines an endpoint /users/{userId}. When a client sends a GET request to https://api.example.com/v1/users/123, the API is expected to return a JSON object representing a user, or a 404 if the user doesn’t exist. The definitions section describes the structure of a User object, ensuring consistency across the API.
The core problem OpenAPI solves is the "it works on my machine" syndrome for APIs. Before standardized specifications like OpenAPI, API consumers and providers had to rely on out-of-band documentation, often leading to misinterpretations, integration headaches, and extensive back-and-forth communication. OpenAPI provides a machine-readable contract that both sides can agree on.
Internally, an OpenAPI document is a JSON or YAML object that describes the API’s endpoints, parameters, request/response bodies, authentication methods, and more. It’s structured into several key sections:
swagger: Specifies the OpenAPI version (e.g., "2.0").info: Contains metadata about the API, like its title, version, and description.host: The domain name of the API.basePath: The base URL path of the API (e.g.,/v1).schemes: The protocol(s) used (e.g.,http,https).paths: The heart of the spec, detailing each API endpoint and the HTTP methods it supports.definitions: Reusable data models that describe the structure of request and response bodies.
The exact levers you control are within the paths and definitions sections. For each endpoint, you define the HTTP method (get, post, put, delete, etc.), the parameters it accepts (in: path, in: query, in: header, in: formData), and the possible responses, including their status codes and the expected structure of their bodies (using $ref to link to definitions). The definitions themselves allow you to precisely model your data types, specifying properties, their types (string, integer, boolean, array, object), and which are required.
When you define a parameter as type: string and required: true in the parameters array for a specific path operation, you are mandating that the client must provide a string value for that parameter. If the parameter is in: path, it must be part of the URL path. If it’s in: query, it must be a URL query parameter. The server implementation then relies on this contract to validate incoming requests. If a required parameter is missing or is of the wrong type, the server should return a 400 Bad Request error.
The most surprising aspect for many is how strictly OpenAPI 2.0 enforces type definitions and parameter validation, acting as a powerful form of contract testing built directly into the API description. If your definitions specify type: integer for a field, and the server receives a string value for that field in a request body, it’s not just a minor inconvenience; it’s a contract violation that should ideally result in an error before your business logic even executes. This rigidity, while sometimes feeling like a burden, is precisely what enables tools to automatically generate client SDKs, server stubs, and interactive documentation that just work.
The next logical step is exploring OpenAPI 3.0, which introduces significant improvements and a more flexible structure.