OpenAPI 3.0 — Spec Overview

# openapi.yaml
openapi: "3.0.3"
info:
  title: "My Backend API"
  version: "1.0.0"
  description: "Production Node.js REST API"
  contact:
    name: "API Support"
    email: "api@example.com"

servers:
  - url: "https://api.example.com/api/v1"
    description: "Production"
  - url: "http://localhost:3000/api/v1"
    description: "Local development"

# ━━ Reusable components ━━
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

  schemas:
    User:
      type: object
      required: [id, email, name, role, createdAt]
      properties:
        id:
          type: string
          format: uuid
          example: "550e8400-e29b-41d4-a716-446655440000"
        email:
          type: string
          format: email
          example: "alice@example.com"
        name:
          type: string
          minLength: 2
          maxLength: 100
          example: "Alice Smith"
        role:
          type: string
          enum: [USER, ADMIN, MODERATOR]
        createdAt:
          type: string
          format: date-time

    CreateUserRequest:
      type: object
      required: [name, email, password]
      properties:
        name:
          type: string
          minLength: 2
        email:
          type: string
          format: email
        password:
          type: string
          minLength: 8

    PaginatedUsers:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/User'
        meta:
          $ref: '#/components/schemas/PaginationMeta'

    PaginationMeta:
      type: object
      properties:
        page: { type: integer }
        limit: { type: integer }
        total: { type: integer }
        totalPages: { type: integer }
        hasNext: { type: boolean }
        hasPrev: { type: boolean }

    ApiError:
      type: object
      required: [success, error]
      properties:
        success:
          type: boolean
          example: false
        error:
          type: object
          required: [code, message]
          properties:
            code:
              type: string
              example: NOT_FOUND
            message:
              type: string

# ━━ Global security (override per route if needed) ━━
security:
  - bearerAuth: []

# ━━ Paths ━━
paths:
  /users:
    get:
      summary: "List users"
      description: "Returns a paginated list of users. Requires ADMIN role."
      operationId: listUsers
      tags: [Users]
      parameters:
        - name: page
          in: query
          schema: { type: integer, minimum: 1, default: 1 }
        - name: limit
          in: query
          schema: { type: integer, minimum: 1, maximum: 100, default: 20 }
      responses:
        '200':
          description: Paginated list of users
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedUsers'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ApiError' }
    post:
      summary: "Create user"
      operationId: createUser
      tags: [Users]
      security: []          # override: this endpoint is public (no auth)
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/CreateUserRequest' }
      responses:
        '201':
          description: User created
          headers:
            Location:
              description: URL of the new resource
              schema: { type: string }
          content:
            application/json:
              schema: { $ref: '#/components/schemas/User' }
        '409':
          description: Email already registered
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ApiError' }