Last updated
What Is OpenAPI / Swagger?
OpenAPI (formerly Swagger) is a specification for describing REST APIs in a machine-readable format (JSON or YAML). An OpenAPI document describes all endpoints, request/response schemas, authentication methods, and parameters. Tools can use this document to generate client SDKs, server stubs, documentation, and test suites automatically.
OpenAPI 3.0 Document Structure
YAML
openapi: 3.0.3
info:
title: My API
version: 1.0.0
description: A sample REST API
servers:
- url: https://api.example.com/v1
paths:
/users:
get:
summary: List all users
operationId: listUsers
parameters:
- name: limit
in: query
schema:
type: integer
default: 20
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/User'
components:
schemas:
User:
type: object
required: [id, email]
properties:
id:
type: integer
email:
type: string
format: email
name:
type: stringOpenAPI Tooling
| Tool | Purpose |
|---|---|
| Swagger UI | Interactive API documentation browser |
| Swagger Editor | Online YAML/JSON editor with live preview |
| OpenAPI Generator | Generate client/server code in 50+ languages |
| Redoc | Beautiful static API documentation |
| Spectral | OpenAPI linting and validation |