OpenAPI Tutorial

Introduction

The OpenAPI Specification (OAS) is a standard format used to describe REST APIs. It is widely used with tools like Swagger. OpenAPI is essential for Clean API documentation, Developer experience, Scalable API systems. It turns your API into a professional, easy-to-use product.

It helps you:

• Document APIs
• Generate client SDKs
• Test endpoints easily

What is OpenAPI?

OpenAPI is a JSON or YAML-based specification that defines:

• Endpoints
• Request/response formats
• Authentication
• Parameters

Example:

API → Defined in YAML/JSON → Used by tools → Documentation generated

Why Use OpenAPI?

• Standardized API documentation
• Easy integration for developers
• Auto-generated docs (Swagger UI)
• Better collaboration between frontend & backend

OpenAPI File Structure

Basic structure:

openapi: 3.0.0
info:
title: Postcode API
version: 1.0.0
paths:
/postcode:
get:
summary: Get postcode details

Key Components

1. Info Section

info:
title: API Name
version: 1.0.0
description: API description

2. Paths (Endpoints)

paths:
/users:
get:
summary: Get users

3. Parameters

parameters:
- name: id
in: query
required: true
schema:
type: string

4. Responses

responses:
200:
description: Success

5. Components (Reusable)

components:
schemas:
User:
type: object

Example: Simple API Definition

openapi: 3.0.0
info:
  title: Sample API
  version: 1.0.0

paths:
  /data:
    get:
      summary: Get data
      responses:
        200:
          
description: Successful response

Swagger UI Integration

Use tools like:

• Swagger UI
• Swagger Editor

They convert OpenAPI file into Interactive API documentation

How OpenAPI Works

With OpenAPI, you can generate a visual interface using Swagger UI.

Steps:

1. Create openapi.yaml
2. Upload to Swagger UI
3. View interactive API docs
4. Test endpoints directly

Authentication in OpenAPI

Example for API Key:

components:
  securitySchemes:
    ApiKeyAuth:
     type: apiKey
     in: header

     name: Authorization

Benefits for Developers

• Easy API testing
• Clear documentation
• Faster integration
• Reduced errors

Common Mistakes

• Missing response schemas
• No authentication defined
• Poor naming conventions
• Incomplete documentation

Best Practices

• Use clear endpoint naming
• Add descriptions for all endpoints
• Include request/response examples
• Version your API (v1, v2)
• Keep documentation updated

Tools for OpenAPI

• Swagger UI – Interactive docs
• Swagger Editor – Write and validate specs
• Postman – Import OpenAPI and test APIs