What is OpenAPI? — REST API Specification Explained

Definition

OpenAPI (formerly known as Swagger) is a specification for describing RESTful APIs using a standard, language-agnostic format. An OpenAPI document (written in YAML or JSON) provides a machine-readable definition of every API endpoint, input parameter, response format, authentication method, and more.

The OpenAPI Specification (OAS) started life as Swagger in 2011, created by Tony Tam and the team at Reverb Technologies. In 2016, the specification was donated to the OpenAPI Initiative under the Linux Foundation and renamed OpenAPI. Swagger remained the name of the tooling ecosystem.

OpenAPI 3.0 vs 3.1

Feature	OpenAPI 3.0	OpenAPI 3.1
JSON Schema	Draft 07 (custom subset)	Full JSON Schema 2020-12
Format	YAML / JSON	YAML / JSON
Webhooks	❌	✅ (native support)
Discriminator Mapping	✅	✅ (improved)
Examples	Multiple examples	Multiple examples (improved)
Null Values	Limited	Full support via `nullable` / `type: null`
Path Parameters	Required by default	Can be declared optional
License Info	SPDX identifier	SPDX identifier (improved)
Release Year	2017	2021

OpenAPI Document Structure

An OpenAPI spec is organized into top-level sections:

openapi: 3.1.0
info:
  title: User Management API
  version: 1.0.0
  description: API for managing users and their posts
  contact:
    name: API Support
    email: support@example.com
  license:
    name: MIT
    identifier: MIT
 
servers:
  - url: https://api.example.com/v1
    description: Production server
  - url: https://staging.example.com/v1
    description: Staging server
 
paths:
  /users:
    get:
      summary: List all users
      ...
    post:
      summary: Create a new user
      ...
 
components:
  schemas:
    User:
      ...
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

Root-Level Fields

Field	Required	Description
`openapi`	✅	OpenAPI specification version
`info`	✅	Metadata about the API
`servers`	❌	Server connection URLs
`paths`	✅	Available endpoints and operations
`components`	❌	Reusable schemas, responses, parameters
`security`	❌	Global security requirements
`tags`	❌	Tag grouping for operations
`externalDocs`	❌	External documentation links

Paths and Operations

Each path defines one or more HTTP methods:

paths:
  /users:
    get:
      tags: [Users]
      summary: Retrieve all users
      operationId: listUsers
      parameters:
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            default: 20
        - name: offset
          in: query
          required: false
          schema:
            type: integer
            default: 0
      responses:
        "200":
          description: A paginated list of users
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/User"
        "401":
          $ref: "#/components/responses/Unauthorized"
 
    post:
      summary: Create a new user
      operationId: createUser
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateUserRequest"
      responses:
        "201":
          description: User created successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/User"
 
  /users/{userId}:
    get:
      summary: Get a user by ID
      operationId: getUser
      parameters:
        - name: userId
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        "200":
          description: The requested user
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/User"
        "404":
          description: User not found

Schemas (Data Models)

Schemas define the structure of request and response data using JSON Schema:

components:
  schemas:
    User:
      type: object
      required: [id, name, email]
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier
        name:
          type: string
          minLength: 1
          maxLength: 100
        email:
          type: string
          format: email
        role:
          type: string
          enum: [admin, user, moderator]
          default: user
        createdAt:
          type: string
          format: date-time
        avatar:
          type: string
          format: uri
          nullable: true
      example:
        id: "550e8400-e29b-41d4-a716-446655440000"
        name: "Alice Johnson"
        email: "alice@example.com"
        role: "admin"
        createdAt: "2026-01-15T10:30:00Z"
        avatar: null
 
    CreateUserRequest:
      type: object
      required: [name, email]
      properties:
        name:
          type: string
        email:
          type: string
          format: email
        role:
          type: string
          enum: [user, moderator]
          default: user

Security Schemes

OpenAPI supports multiple authentication methods:

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Enter your JWT token
 
    apiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: Enter your API key
 
    basicAuth:
      type: http
      scheme: basic
      description: HTTP Basic authentication
 
    oauth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://auth.example.com/authorize
          tokenUrl: https://auth.example.com/token
          scopes:
            read: Read access
            write: Write access
 
# Apply globally or per-operation
security:
  - bearerAuth: []

Code Generation

One of OpenAPI's most powerful features is code generation. Tools like OpenAPI Generator and Swagger Codegen can generate:

Artifact	Examples
Server stubs	Node.js, Python, Go, Java, Ruby, PHP, Rust
Client SDKs	TypeScript, Python, Swift, Kotlin, Java
API documentation	Swagger UI, Redoc, Stoplight
API tests	Postman collections, REST Assured, pytest
Infrastructure	Terraform, Kubernetes manifests

# Generate a TypeScript client
npx @openapitools/openapi-generator-cli generate \
  -i spec.yaml \
  -g typescript-fetch \
  -o ./generated/client
 
# Generate a Python server
npx @openapitools/openapi-generator-cli generate \
  -i spec.yaml \
  -g python-flask \
  -o ./generated/server

Swagger UI

Swagger UI renders OpenAPI specifications into interactive documentation:

<!DOCTYPE html>
<html>
<head>
  <link rel="stylesheet" type="text/css"
    href="https://unpkg.com/swagger-ui-dist/swagger-ui.css" />
</head>
<body>
  <div id="swagger-ui"></div>
  <script src="https://unpkg.com/swagger-ui-dist/swagger-ui-bundle.js">
  </script>
  <script>
    SwaggerUIBundle({
      url: "/openapi.yaml",
      dom_id: "#swagger-ui",
    });
  </script>
</body>
</html>

Swagger UI features include:

Interactive endpoint testing — Try requests directly in the browser
Schema exploration — View request/response models
Authentication — Enter API keys and tokens
Download — Export specification files

LangStop OpenAPI & API Tools

OpenAPI Editor — Design and validate OpenAPI 3.x specifications
OpenAPI Diff — Compare OpenAPI specifications side by side
REST API Client — Send HTTP requests and test API endpoints
JSON Schema GUI Builder — Visually build JSON schemas
JSON Validator — Validate JSON syntax