Getting Started with MockForge

Welcome to MockForge! This guide will get you up and running in minutes. MockForge is a powerful, multi-protocol mocking framework that helps frontend and backend teams work in parallel by providing realistic API mocks.

Table of Contents

What is MockForge?

MockForge is a comprehensive mocking framework that supports multiple protocols:

  • HTTP/REST APIs - Mock REST endpoints from OpenAPI/Swagger specs
  • WebSocket - Simulate real-time connections with replay and interactive modes
  • gRPC - Mock gRPC services from .proto files
  • GraphQL - Generate mock resolvers from GraphQL schemas

Why MockForge?

  • 🚀 Fast Setup: Go from OpenAPI spec to running mock server in seconds
  • 🔄 Multi-Protocol: Mock HTTP, WebSocket, gRPC, and GraphQL in one tool
  • 🎯 Realistic Data: Generate intelligent mock data with faker functions and templates
  • 🔌 Extensible: Plugin system for custom authentication, templates, and data sources
  • 📊 Admin UI: Visual interface for monitoring and managing mock servers

The Five Pillars of MockForge

MockForge is built on five foundational pillars that guide every feature we build. Understanding these pillars helps you see how MockForge delivers value across different aspects of API mocking:

[Reality] – Everything that makes mocks feel like a real, evolving backend

Make mocks indistinguishable from production backends through realistic behavior, state management, and dynamic data generation. Features like Reality Continuum, Smart Personas, Chaos Lab, and Temporal Simulation ensure your mocks behave like real systems.

Key Features:

  • Reality Continuum and Reality Slider for configurable realism levels
  • Smart Personas for consistent cross-endpoint data generation
  • Generative Schema Mode for dynamic mock data without seed data
  • Chaos Lab for network condition simulation
  • Multi-protocol support (HTTP, gRPC, WebSocket, Kafka, MQTT, AMQP, SMTP, FTP, TCP)

[Contracts] – Schema, drift, validation, and safety nets

Ensure API contracts are correct, validated, and stay in sync with real backends. Features like AI Contract Diff, automatic API sync, and comprehensive validation help catch breaking changes before they reach production.

Key Features:

  • OpenAPI/GraphQL schema validation
  • AI Contract Diff for contract comparison and visualization
  • Automatic API Sync & Change Detection
  • Request/response validation with detailed error reporting
  • Contract drift detection and monitoring

[DevX] – SDKs, generators, playgrounds, ergonomics

Make MockForge effortless to use, integrate, and extend for developers. Native SDKs for 6 languages, client code generators, interactive playgrounds, and comprehensive tooling ensure a smooth developer experience.

Key Features:

  • Multi-language SDKs (Rust, Node.js, Python, Go, Java, .NET)
  • Client code generators (React, Vue, Angular, Svelte)
  • GraphQL + REST Playground
  • CLI tool and Admin UI
  • Plugin system for extensibility

[Cloud] – Registry, orgs, governance, monetization, marketplace

Enable team collaboration, sharing, and scaling from solo developers to enterprise organizations. Cloud workspaces, scenario marketplace, registry server, and organization management help teams work together effectively.

Key Features:

  • Cloud Workspaces for team collaboration
  • Scenario Marketplace for sharing mock scenarios
  • Registry Server for centralized distribution
  • Organization Management for enterprise teams
  • Security controls and governance

[AI] – LLM/voice flows, AI diff/assist, generative behaviors

Leverage artificial intelligence to automate mock generation, enhance data realism, and assist developers. AI-powered features like MockAI, voice interface, and intelligent contract analysis make mock creation effortless.

Key Features:

  • MockAI for intelligent mock generation from natural language
  • Voice + LLM Interface for voice-driven mock creation
  • AI Contract Diff for intelligent contract analysis
  • AI Event Streams for narrative-driven WebSocket events
  • Generative data behaviors with RAG-powered synthesis

Learn More: See the complete Pillars documentation for detailed information about each pillar, feature mappings, and examples.

Choose Your Path

Depending on your role, team, or use case, you may want to start with a specific pillar:

  • Reality-First Onboarding - Start here if you care about realism. Perfect for frontend teams needing realistic data that evolves over time.
  • Contracts-First Onboarding - Start here if you’re a Platform/API team. Perfect for teams needing contract validation and drift detection.
  • AI-First Onboarding - Start here if you want natural-language-driven mocks. Perfect for rapid prototyping and AI-powered mock generation.

See Journeys by Pillar for a complete overview of all pillar-first onboarding journeys.

Installation

Prerequisites

MockForge requires one of:

  • Rust toolchain (for cargo install)
  • Docker (for containerized deployment)
cargo install mockforge-cli

Verify installation:

mockforge --version

Method 2: Docker

# Build the Docker image
git clone https://github.com/SaaSy-Solutions/mockforge.git
cd mockforge
docker build -t mockforge .

# Run with default ports
docker run -p 3000:3000 -p 3001:3001 -p 9080:9080 mockforge

Method 3: Build from Source

git clone https://github.com/SaaSy-Solutions/mockforge.git
cd mockforge
cargo build --release

# Install globally
cargo install --path crates/mockforge-cli

See Installation Guide for detailed instructions and troubleshooting.

Quick Start: Your First Mock API

Let’s create a simple mock API in 3 steps:

Step 1: Create an OpenAPI Specification

Create a file my-api.yaml:

openapi: 3.0.3
info:
  title: My First API
  version: 1.0.0
paths:
  /users:
    get:
      summary: List users
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'
    post:
      summary: Create user
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/User'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
  /users/{id}:
    get:
      summary: Get user by ID
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
components:
  schemas:
    User:
      type: object
      required:
        - id
        - name
        - email
      properties:
        id:
          type: string
          example: "{{uuid}}"
        name:
          type: string
          example: "John Doe"
        email:
          type: string
          format: email
          example: "[email protected]"
        createdAt:
          type: string
          format: date-time
          example: "{{now}}"

Step 2: Start MockForge with Your Spec

mockforge serve --spec my-api.yaml --http-port 3000

You should see:

🚀 MockForge v1.0.0 starting...
📡 HTTP server listening on 0.0.0.0:3000
📋 OpenAPI spec loaded from my-api.yaml
✅ Ready to serve requests at http://localhost:3000

Step 3: Test Your Mock API

Open a new terminal and test your endpoints:

# List users
curl http://localhost:3000/users

# Get a specific user
curl http://localhost:3000/users/123

# Create a user
curl -X POST http://localhost:3000/users \
  -H "Content-Type: application/json" \
  -d '{"name": "Jane Smith", "email": "[email protected]"}'

Congratulations! You have a working mock API! 🎉

Enable Dynamic Data (Optional)

To get unique data on each request, enable template expansion:

# Stop the server (Ctrl+C), then restart with templates enabled
MOCKFORGE_RESPONSE_TEMPLATE_EXPAND=true \
  mockforge serve --spec my-api.yaml --http-port 3000

Now {{uuid}} and {{now}} in your spec will generate unique values!

Basic Configuration

Using a Configuration File

Create mockforge.yaml for better control:

http:
  port: 3000
  openapi_spec: my-api.yaml
  response_template_expand: true
  cors:
    enabled: true
    allowed_origins: ["http://localhost:3000"]

admin:
  enabled: true
  port: 9080

logging:
  level: info

Start with the config file:

mockforge serve --config mockforge.yaml

Environment Variables

All settings can be set via environment variables:

export MOCKFORGE_HTTP_PORT=3000
export MOCKFORGE_ADMIN_ENABLED=true
export MOCKFORGE_RESPONSE_TEMPLATE_EXPAND=true
export MOCKFORGE_LOG_LEVEL=debug

mockforge serve --spec my-api.yaml

See Configuration Reference for all options.

Common Use Cases

Frontend Development

Start a mock server and point your frontend to it:

# Terminal 1: Start mock server
mockforge serve --spec api.json --http-port 3000 --admin

# Terminal 2: Point frontend to mock server
export REACT_APP_API_URL=http://localhost:3000
npm start

API Contract Testing

Test that your API matches the OpenAPI specification:

# Request validation defaults to "enforce"; set it explicitly with an env var
MOCKFORGE_REQUEST_VALIDATION=enforce mockforge serve --spec api.json \
  --http-port 3000

Team Collaboration

Share mock configurations via Git:

# Commit your mock config
git add mockforge.yaml
git commit -m "Add user API mocks"

# Team members can use the same mocks
git pull
mockforge serve --config mockforge.yaml

Next Steps

Now that you have MockForge running, explore these resources:

Tutorials

User Guides

Reference

Examples

Troubleshooting

Server Won’t Start

# Check if port is in use
lsof -i :3000

# Use a different port
mockforge serve --spec my-api.yaml --http-port 3001

Templates Not Working

Enable template expansion:

MOCKFORGE_RESPONSE_TEMPLATE_EXPAND=true mockforge serve --spec my-api.yaml

Need More Help?

Ready to dive deeper? Continue to the 5-Minute Tutorial or explore all available examples.