OpenAPI is not a tool, but a specification that describes RESTful APIs.
Here’s how it works in practice. Imagine you’re building a service that manages user profiles. You’d define your API using OpenAPI.
openapi: 3.0.0
info:
title: User Profile API
version: 1.0.0
servers:
- url: http://localhost:3000/v1
paths:
/users:
get:
summary: Get a list of users
responses:
'200':
description: A list of users
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/User'
post:
summary: Create a new user
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/NewUser'
responses:
'201':
description: User created successfully
components:
schemas:
User:
type: object
properties:
id:
type: string
format: uuid
name:
type: string
email:
type: string
format: email
NewUser:
type: object
properties:
name:
type: string
email:
type: string
format: email
required:
- name
- email
This YAML file is the contract. It specifies endpoints like /users, the HTTP methods allowed (GET, POST), what data to expect in requests (like NewUser schema for POST), and what data to return (like User schema for GET).
Now, about the "tools." Swagger is an older, but still widely used, set of tools that implements the OpenAPI specification. Think of OpenAPI as the blueprint, and Swagger as the construction company that builds things from that blueprint. The most famous Swagger tool is the Swagger UI.
When you point Swagger UI at your OpenAPI definition (the YAML above), it generates an interactive documentation page.
Here’s a snippet of what you’d see in Swagger UI:
User Profile API v1.0.0
Base URL: http://localhost:3000/v1
/users
GET
Summary: Get a list of users
Responses:
200 OK
Description: A list of users
Content:
application/json:
Schema:
type: array
items: User
POST
Summary: Create a new user
Request Body:
Content:
application/json:
Schema: NewUser
Responses:
201 Created
Description: User created successfully
You can actually try out the API directly from this documentation. Click "Try it out," fill in parameters or request bodies, and hit "Execute." Swagger UI sends the request to your running API and shows you the response. This is incredibly useful for developers consuming your API.
Redoc is another tool that renders OpenAPI specifications, but it focuses on a clean, human-readable documentation experience. It doesn’t typically offer the "Try it out" functionality like Swagger UI.
Here’s what a Redoc-generated page might look like for the same API:
User Profile API v1.0.0
Get a list of users
GET /users
Returns a list of users.
Responses
200 OK
Description: A list of users
Content
application/json:
Schema:
type: array
items: User
Create a new user
POST /users
Request body
Content
application/json:
Schema: NewUser
Properties
name: string
email: string (format: email)
Required: name, email
Responses
201 Created
Description: User created successfully
Redoc presents the information more like a traditional API reference manual. It’s great for quickly understanding what an API does and its structure.
The key takeaway is that OpenAPI is the standard, and Swagger and Redoc are tools that help you work with that standard. Swagger (especially Swagger UI) is known for its interactive testing capabilities, while Redoc excels at creating polished, readable documentation. Many teams use both: Swagger UI for development and internal testing, and Redoc for public-facing documentation.
What most people don’t realize is that the example or examples fields within an OpenAPI schema are not just for display; they can be used by code generation tools to provide default values or sample data structures, and by some documentation generators to populate the "Try it out" fields with pre-filled, realistic data.
The next step is to explore how these tools can be used for API security definition and client/server code generation.