What is OpenAPI
OpenAPI (previously known as Swagger) is a standard format for describing REST APIs in a machine-readable way — usually written in YAML or JSON.
It is called blueprint for an API
Example of a Minimal OpenAPI Spec (YAML)
openapi: 3.0.0
info:
title: Example API
version: 1.0.0
description: Simple API that returns a greeting message.
servers:
- url: https://api.example.com
paths:
/hello:
get:
summary: Returns a greeting message
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: "Hello, world!"
What You See Here
| Section | Meaning |
|---|---|
openapi: 3.0.0 | Version of the OpenAPI standard |
info | Basic info about the API |
servers | Where the API is hosted |
paths | All available endpoints (e.g. /hello) |
get | HTTP method (GET, POST, etc.) |
responses | Expected responses and their structure |
You can practise here https://editor.swagger.io
Basic Structure of an OpenAPI Spec
An OpenAPI document describes your entire API in a structured way.
It’s made up of a few top-level sections that always appear in a spec file
Let’s visualize it first:
openapi: 3.0.0 ← version of OpenAPI standard
info: ← general info about your API
servers: ← where your API lives (base URLs)
paths: ← endpoints and operations
components: ← reusable pieces (schemas, responses, etc.)
security: ← global auth requirements (optional)
tags: ← optional categories for grouping
externalDocs: ← links to external docs (optional)