How do you document a REST API with OpenAPI / Swagger?
Learn how to document a REST API using OpenAPI and Swagger UI: define paths, components, and schemas for interactive docs and generated SDKs.
Expected Interview Answer
You document a REST API with OpenAPI by writing a machine-readable specification (YAML or JSON) that describes every path, method, parameter, request body, response, and schema, then render it as interactive docs with Swagger UI.
OpenAPI (formerly Swagger) is the standard contract format for HTTP APIs. A single spec file defines info, servers, paths with operations, reusable components (schemas, parameters, security schemes), and examples. From that one file you generate interactive Swagger UI docs, client SDKs, server stubs, and request validators. Teams either write the spec first (design-first) or generate it from code annotations (code-first), then keep it in version control and validate it in CI.
- Single source of truth for the API contract
- Interactive try-it-out docs via Swagger UI
- Auto-generated client SDKs and server stubs
- Contract testing and request validation
- Easier onboarding for API consumers
AI Mentor Explanation
An OpenAPI spec is like the official laws of cricket printed in one rulebook every player, umpire, and scorer shares. It states precisely what each delivery, appeal, and dismissal means, so nobody argues about interpretation. Give the same rulebook to a new umpire and they officiate correctly, just as a shared spec lets any developer consume the API without guessing.
Step-by-Step Explanation
Step 1
Choose design-first or code-first
Either hand-write the OpenAPI YAML before coding, or generate it from framework annotations and decorators.
Step 2
Define info and servers
Set the openapi version, title, version, and the server base URLs the API is hosted on.
Step 3
Describe paths and operations
For each path, document the HTTP methods, parameters, request bodies, and every possible response status.
Step 4
Reuse components
Define shared schemas, parameters, and security schemes under components and reference them with $ref to avoid duplication.
Step 5
Render and validate
Serve the spec through Swagger UI for interactive docs and lint or validate it in CI so it never drifts from the real API.
What Interviewer Expects
- OpenAPI is the spec, Swagger UI renders it
- Knowledge of paths, operations, and components
- Design-first vs code-first workflows
- Reuse via $ref and reusable schemas
- Keeping the spec in version control and CI
Common Mistakes
- Confusing OpenAPI the spec with Swagger the tooling
- Documenting only happy-path responses, not errors
- Letting the spec drift out of sync with the code
- Duplicating schemas instead of using $ref components
- Omitting security schemes and authentication details
Best Answer (HR Friendly)
“OpenAPI, often called Swagger, is a standard way to write down exactly how an API works in one structured file. That file can be turned into interactive documentation and even auto-generate code, so anyone using the API knows what to send and what to expect.”
Code Example
openapi: 3.0.3
info:
title: Orders API
version: 1.0.0
servers:
- url: https://api.example.com/v1
paths:
/orders/{id}:
get:
summary: Get an order
parameters:
- name: id
in: path
required: true
schema: { type: string }
responses:
'200':
description: Order found
content:
application/json:
schema:
$ref: '#/components/schemas/Order'
'404':
description: Not found
components:
schemas:
Order:
type: object
properties:
id: { type: string }
total: { type: number }Follow-up Questions
- What is the difference between OpenAPI and Swagger?
- How do you keep the spec in sync with the code?
- What are components and $ref used for?
- How would you document authentication in OpenAPI?
- Can you generate client SDKs from an OpenAPI file?
MCQ Practice
1. What is Swagger UI in relation to OpenAPI?
Swagger UI reads an OpenAPI spec and renders interactive, try-it-out documentation from it.
2. Where do reusable schemas live in an OpenAPI document?
Reusable schemas, parameters, and security schemes are defined under components and referenced with $ref.
3. What does design-first mean?
Design-first means authoring the OpenAPI contract first, then implementing the API to match it.
Flash Cards
OpenAPI vs Swagger? — OpenAPI is the specification standard; Swagger is the tooling ecosystem (like Swagger UI) built around it.
What is $ref used for? — Referencing reusable components such as schemas and parameters to avoid duplication.
Design-first vs code-first? — Design-first writes the spec before coding; code-first generates the spec from code annotations.
What renders interactive docs? — Swagger UI renders an OpenAPI spec into interactive, try-it-out documentation.
Continue Learning
Related Interview Questions
What is a REST API and what are the core principles of REST?
easy
What are the main HTTP methods and how do they map to CRUD operations?
easy
How would you design a machine-readable error format for a REST API?
medium
Which REST API changes are breaking, and how do you evolve a contract without a new version?
medium