API Fundamentals
/Advanced
OpenAPI Specification
Definition
A widely adopted, language-agnostic standard for describing the structure of REST APIs. It defines endpoints, input parameters, and output JSON schemas in a strictly formatted YAML or JSON document.
Explain Like I'm New
It's the architectural blueprint of an API. Instead of writing a Word document explaining how your API works, you write a machine-readable OpenAPI file. Other programs can read this file to automatically generate documentation, generate API clients, or generate testing suites.
Real World Example
Writing an `openapi.yaml` file. A tool reads it and automatically creates a beautiful Swagger webpage. Another tool reads it and automatically generates a complete TypeScript SDK for frontend developers to download.
Common Use Cases
- •Standardizing documentation
- •Code generation
- •API discovery
Terminal Output
bash / terminal
# A simple openapi.yaml blueprint
openapi: 3.0.0
info:
title: My Simple API
version: 1.0.0
paths:
/users:
get:
summary: Get all users
responses:
'200':
description: A list of users
content:
application/json:
schema:
type: array
items:
type: object
properties:
id:
type: integer
name:
type: string
Interview Questions
basic
- Is the OpenAPI Specification tied to a specific programming language like Java or Node.js?
intermediate
- What is the difference between OpenAPI and Swagger?