Server Generator Guide

Contents

1. Overview
2. Installation
3. Prerequisites
4. Quick Start: End-to-End Example
5. Architecture
6. Operating Modes
7. Common CLI Flags
8. OpenAPI Generator
9. gRPC Generator
10. MCP Generator
11. GraphQL Generator
12. SOAP Generator
13. Kafka Generator
14. RabbitMQ Generator
15. SSE Generator
16. Socket Generator
17. SMTP Generator
18. HAR Import
19. Smart Merge Strategy
20. Orchestrator Mode
21. Experimental UI
22. Generated Server Environment Variables
23. Generated Server UI and Caching
24. Output Structure & Offline Build
25. Docker Build
26. CI/CD Pipeline Examples
27. Mock Examples
28. Limitations

About URLs in examples: All examples use localhost:5770 as the default Mockarty address. If your instance runs on a remote server, replace localhost:5770 with its actual address (e.g. https://mockarty.company.com or http://192.168.1.50:5770). See Tips & Useful Features for details.

Overview

What is a “Generated Server”?

Think of Mockarty as a brain that knows how to respond to requests, and a generated server as a translator that speaks a specific protocol. For example, if your application talks gRPC, you generate a gRPC server that translates gRPC calls into something Mockarty understands. The generated server is a small, standalone program that you can run anywhere – it receives requests in its native protocol (gRPC, Kafka, SOAP, etc.), asks Mockarty “what should I respond?”, and returns the answer. This way, you can mock any protocol without writing protocol-specific code yourself.

Mockarty Server Generator is a unified code generation binary (mockarty-server-generator) that supports 10 protocol types. From a single binary you can generate standalone Go servers, create mocks via API, or manage multiple servers through an orchestrator UI.

The generators are divided into two categories:

• Spec-based generators (OpenAPI, gRPC, MCP, GraphQL, SOAP) — generate servers from protocol specifications and can automatically create mocks from the spec via the -create-mocks flag.
• Config-based adapters (Kafka, RabbitMQ, SSE, Socket, SMTP) — generate servers from a JSON/YAML configuration file. These adapters connect to real infrastructure (e.g. Kafka brokers, RabbitMQ) or provide protocol endpoints (SSE, WebSocket, SMTP) and resolve mock responses via Mockarty. Mocks for adapters must be created manually through the Mockarty UI or API.

Each generated server connects to the Mockarty HTTP node (admin or resolver) for mock resolution. The generated servers are fully autonomous Go programs with embedded UI, vendored dependencies, and optional high-performance caching.

Supported Protocols

Installation

Download the pre-built mockarty-server-generator binary for your platform from the GitHub Releases page.

# Linux / macOS
chmod +x mockarty-server-generator

# Verify
./mockarty-server-generator --help

The binary is self-contained and requires no additional dependencies.

Prerequisites

Before using the server generator, make sure you have:

Running Mockarty Instance

A running Mockarty admin node is required. Generated servers do not work standalone — they call the Mockarty HTTP node for mock resolution on every request.

# Verify Mockarty is running
curl http://localhost:5770/health

If you don’t have Mockarty running yet, follow the Quick Start Guide.

Go SDK (for building generated servers)

The generator produces Go source code with vendored dependencies. To build the generated server into a binary, you need the Go toolchain installed:

• Minimum version: Go 1.21+
• Download: https://go.dev/dl/

# Verify Go is installed
go version
# go version go1.24.1 linux/amd64

Why Go? The generated servers are Go programs because Go compiles to a single static binary with zero runtime dependencies, fast startup, low memory usage, and built-in concurrency support. You don’t need to know Go — just run go build and use the binary.

No Go? No problem. If you can’t install Go, use the Orchestrator mode — it builds and runs generated servers automatically, or use Docker (see Docker Build).

License Requirement

Mock creation (-create-mocks flag) and orchestrator/experimental-ui modes require a valid Mockarty license with the mock feature enabled.

Check your license at Settings > License in the Mockarty Web UI, or via API:

curl -H "Authorization: Bearer mk_your_token" http://localhost:5770/api/v1/license

API Token

To create mocks, you need a user API token (mk_* format). Create one at Settings > API Tokens in the Mockarty Web UI.

Quick Start: End-to-End Example

This example takes you from an OpenAPI spec to a running mock server in under 5 minutes.

Step 1: Generate the server and create mocks

./mockarty-server-generator openapi \
  -input https://petstore3.swagger.io/api/v3/openapi.json \
  -output ./petstore-server/server.go \
  -package main \
  -create-mocks \
  -api-token mk_your_token_here \
  -namespace sandbox \
  -tags "petstore,demo"

This command does two things simultaneously:

• Creates mock definitions in Mockarty (namespace sandbox)
• Generates a complete Go project in ./petstore-server/

Step 2: Build the binary

cd petstore-server
go build -mod=vendor -o petstore-server .

The -mod=vendor flag tells Go to use the vendored dependencies (no internet required).

Step 3: Run the server

HTTP_PORT=8080 \
HTTP_ADMIN_BASE_URL=http://localhost:5770 \
NAMESPACE=sandbox \
./petstore-server

Step 4: Test it

# Swagger UI
open http://localhost:8080/swagger/

# Health check
curl http://localhost:8080/health

# Call a mocked endpoint
curl http://localhost:8080/pet/1

The generated server receives your request, sends it to Mockarty for mock resolution, and returns the matched mock response.

What you get

petstore-server/
├── server.go        # ~5000 lines of generated Go code
├── go.mod           # Go module definition
├── go.sum           # Dependency checksums
├── vendor/          # ALL dependencies (offline build)
├── assets/          # Swagger UI JS/CSS
└── webfonts/        # Icon fonts

After go build, the petstore-server binary is a single executable (~15-20 MB) that you can copy to any machine with the same OS/architecture. No Go, no dependencies, nothing else needed to run it.

Architecture

All generated servers follow the same pattern: receive a protocol-specific request, translate it into a mock resolution call to the Mockarty HTTP node, and return the mock response back to the client.

Mock Resolution Endpoints

Proxying

When a mock has proxy.target configured, proxying is always performed on the Mockarty HTTP node side, not in the generated server. The flow:

1. Generated server sends request to HTTP node
2. HTTP node finds the mock with proxy.target
3. HTTP node creates a client (MCP, gRPC, etc.) and calls the real service
4. HTTP node logs and returns the response to the generated server

Operating Modes

The server generator binary has three operating modes:

Mode 1: Generate Server Code

Generates a standalone Go server file with all dependencies vendored for offline build.

mockarty-server-generator openapi \
  -input swagger.json \
  -output server.go \
  -package main

Mode 2: Generate Server + Create Mocks

Generates the server and simultaneously creates mocks on the Mockarty HTTP node via API.

mockarty-server-generator openapi \
  -input swagger.json \
  -output server.go \
  -package main \
  -create-mocks \
  -api-token mk_your_token \
  -namespace sandbox

Mode 3: Create Mocks Only (API-First)

Creates mocks on the HTTP node without generating any server code. Useful for populating mocks from a spec when you don’t need a standalone server.

mockarty-server-generator openapi \
  -input swagger.json \
  -create-mocks \
  -api-token mk_your_token \
  -namespace sandbox \
  -tags "petstore,v2"

Note: The -create-mocks mode requires a valid license with the mock feature enabled on the Mockarty HTTP node. Auto mock creation is only supported for spec-based generators (OpenAPI, gRPC, MCP, GraphQL, SOAP). Config-based adapters (Kafka, RabbitMQ, SSE, Socket, SMTP) require manual mock creation through the Mockarty UI or API.

Common CLI Flags

Usage: mockarty-server-generator <generator-type> [flags]

Input/Output Flags

Mock Creation Flags

Update Strategy Flags

Default behavior: When -force-update is not specified, smart merge is used — preserves user customizations while updating schema from the spec.

Spec Fetching Flags

Performance Flags

OpenAPI Generator

Generates HTTP REST mock servers from OpenAPI 2.0 (Swagger) or OpenAPI 3.x specifications.

Input Sources

• Local JSON or YAML file
• URL to a Swagger/OpenAPI spec (JSON or YAML)

Usage

# From local file
mockarty-server-generator openapi \
  -input ./petstore.yaml \
  -output server.go \
  -package main \
  -http-admin-base-url http://localhost:5770 \
  -namespace sandbox

# From URL
mockarty-server-generator openapi \
  -input https://petstore3.swagger.io/api/v3/openapi.json \
  -output server.go \
  -package main

# Create mocks only (no server code)
mockarty-server-generator openapi \
  -input ./petstore.yaml \
  -create-mocks \
  -api-token mk_your_token \
  -namespace sandbox \
  -tags "petstore,v3"

# Generate server + create mocks with smart merge
mockarty-server-generator openapi \
  -input ./petstore.yaml \
  -output server.go \
  -package main \
  -create-mocks \
  -api-token mk_your_token \
  -namespace sandbox

# Force overwrite existing mocks
mockarty-server-generator openapi \
  -input ./petstore.yaml \
  -create-mocks \
  -api-token mk_your_token \
  -force-update

# With request body decomposition and header conditions
mockarty-server-generator openapi \
  -input ./petstore.yaml \
  -create-mocks \
  -api-token mk_your_token \
  -decompose-request-body \
  -use-headers-as-conditions

Advanced Options

• -decompose-request-body — when the spec has oneOf/anyOf request bodies, creates a separate mock per variant with appropriate conditions
• -use-headers-as-conditions — generates conditions from header parameters (e.g., Authorization, X-Request-ID)
• -path-prefix — adds a prefix to all routes: namespace/path-prefix/original-route

Generated Server Features

• Embedded Swagger UI at /swagger/ with the original OpenAPI spec
• Admin UI at /ui with service overview
• Health endpoint at /health
• All API paths mapped to mock resolution

gRPC Generator

Generates gRPC mock servers from .proto files. The generator parses proto files dynamically via protoreflect — you do not need to install protoc, protoc-gen-go, protoc-gen-go-grpc, or any other protobuf toolchain.

Proto File Requirements

Just give Mockarty your .proto files as-is. There is nothing special to add or change before uploading:

• option go_package is not required. If it is missing, Mockarty generates one for you from the package declaration and file path.
• Prefix format does not matter. If go_package is present with any value ("/acme/svc", "acme/svc", "example.com/acme/svc;svc", etc.), Mockarty normalizes it internally.
• Language-specific options are ignored. java_package, php_namespace, csharp_namespace, swift_prefix, objc_class_prefix, ruby_package and similar are stripped automatically — they don’t need to be removed from your files.
• Imports are resolved from the uploaded directory structure. Keep your existing layout intact. Google well-known types (google/protobuf/*) and validate/validate.proto are bundled and resolved automatically.

That’s it — no sed replacements, no manual prefixing, no plugin configuration.

Input Sources

• Directory containing .proto files (or a single .proto file)
• gRPC reflection URL — grpc://host:port or grpc+reflection://host:port (mock creation only, server generation from reflection is not yet supported)

Usage

# From local proto directory
mockarty-server-generator grpc \
  -input ./proto/ \
  -output server.go \
  -package main \
  -http-admin-base-url http://localhost:5770 \
  -namespace sandbox

# With server name (important for mock matching in multi-instance setups)
mockarty-server-generator grpc \
  -input ./proto/ \
  -output server.go \
  -package main \
  -server-name my-grpc-service

# Create mocks only from proto files
mockarty-server-generator grpc \
  -input ./proto/ \
  -create-mocks \
  -api-token mk_your_token \
  -namespace sandbox \
  -server-name my-grpc-service

# Create mocks only from a running gRPC server via reflection
mockarty-server-generator grpc \
  -input grpc://localhost:50051 \
  -create-mocks \
  -api-token mk_your_token \
  -namespace sandbox \
  -server-name my-grpc-service

Features

• Parses .proto files directly via protoreflect — no protoc, plugins, or external toolchain needed
• Accepts proto files with or without go_package; normalizes them automatically
• Generates Go types inline from proto messages
• Handles Google well-known types: Timestamp, Duration, Empty, Struct, Value, wrapper types
• Bundles and resolves validate/validate.proto imports automatically
• gRPC reflection support for discovering services from a running server (mock creation mode)
• Admin UI at /ui with service/method browser and interactive Tester tab

Generated Server Ports

Limitations

• Full support for unary methods only
• Stream methods have basic support (no proxy/delay/error features)
• Server code generation from gRPC reflection is not yet supported (use .proto files for code generation; reflection works for mock creation only)
• Proxying is performed on the HTTP node side, not in the generated server

MCP Generator

Generates Model Context Protocol servers from multiple input sources.

Input Sources

1. MCP server URL — connects to a running MCP server via introspection to discover tools
2. MCP schema JSON — direct schema file with tools definition
3. Swagger/OpenAPI — converts REST endpoints to MCP tools
4. JSON/YAML config — manual tool definitions

Usage

# From running MCP server (introspection)
mockarty-server-generator mcp \
  -input http://localhost:8910/sse \
  -output server.go \
  -package main

# From JSON config
mockarty-server-generator mcp \
  -input mcp-server.json \
  -output server.go \
  -package main \
  -http-admin-base-url http://localhost:5770

# From Swagger spec (convert REST to MCP tools)
mockarty-server-generator mcp \
  -input http://localhost:5770/swagger/doc.json \
  -output server.go \
  -package main

# Create mocks only
mockarty-server-generator mcp \
  -input mcp-server.json \
  -create-mocks \
  -api-token mk_your_token \
  -namespace sandbox

Configuration Format

{
  "server": {
    "name": "example-mcp-server",
    "version": "1.0.0",
    "description": "Server description"
  },
  "tools": [
    {
      "name": "tool_name",
      "description": "Tool description",
      "inputSchema": {
        "type": "object",
        "properties": {
          "param1": {
            "type": "string",
            "description": "Parameter description"
          }
        },
        "required": ["param1"]
      }
    }
  ],
  "config": {
    "httpAdminBaseUrl": "http://localhost:5770",
    "namespace": "sandbox",
    "transport": "sse"
  },
  "proxy": {
    "target": "http://localhost:5772/mcp"
  }
}

Transports

Generated Server Endpoints

• SSE stream: http://localhost:8910/sse
• Message endpoint: http://localhost:8910/message
• Admin UI: http://localhost:8080/ui (MCP Tester)
• Health: http://localhost:8080/health

GraphQL Generator

Generates GraphQL mock servers from schema files, URLs (introspection), or JSON/YAML configs.

Input Sources

1. .graphql / .gql files — local GraphQL schema files (SDL)
2. URL — connects to a running GraphQL endpoint and performs introspection
3. Directory — scans for all .graphql/.gql files and combines them
4. JSON/YAML config — configuration with schema definition

Usage

# From GraphQL schema file
mockarty-server-generator graphql \
  -input ./schema.graphql \
  -output server.go \
  -package main \
  -http-admin-base-url http://localhost:5770 \
  -namespace sandbox

# From running GraphQL endpoint (introspection)
mockarty-server-generator graphql \
  -input http://localhost:4000/graphql \
  -output server.go \
  -package main

# From directory with multiple schema files
mockarty-server-generator graphql \
  -input ./schemas/ \
  -output server.go \
  -package main

# Create mocks only
mockarty-server-generator graphql \
  -input ./schema.graphql \
  -create-mocks \
  -api-token mk_your_token \
  -namespace sandbox \
  -tags "graphql,v1"

Features

• Batch mock creation with concurrent update optimization
• Smart merge, force update modes
• Supports queries and mutations
• Admin UI at /ui with GraphQL Playground (interactive explorer with autocomplete)
• Schema introspection at /graphql

Generated Server Ports

SOAP Generator

Generates SOAP mock servers from WSDL definitions with optional XSD enrichment.

Input Sources

• WSDL file (local)
• WSDL URL
• Directory with WSDL/XSD files (auto-discovers XSD imports)

Usage

# From WSDL file
mockarty-server-generator soap \
  -input ./service.wsdl \
  -output server.go \
  -package main

# From WSDL URL
mockarty-server-generator soap \
  -input http://example.com/service?wsdl \
  -output server.go \
  -package main

# Create mocks only
mockarty-server-generator soap \
  -input ./service.wsdl \
  -create-mocks \
  -api-token mk_your_token \
  -namespace sandbox

Important: Dual-Port Architecture

SOAP generated servers use two separate HTTP ports because the SOAP endpoint uses a wildcard route (/*path) that conflicts with static routes:

Running

HTTP_PORT=8080 ADMIN_PORT=8081 ./soap_server

Features

• Parses WSDL 1.1 with XSD import resolution
• Embedded SOAP Tester UI at /ui (on admin port)
• Matches requests by SOAPAction header and path
• Health endpoint at /health (on admin port)

Kafka Generator

Generates a Kafka adapter server that connects to a real Apache Kafka cluster, consumes messages from specified topics, and resolves mock responses via the Mockarty HTTP node. The generated server acts as a bridge between your Kafka infrastructure and Mockarty’s mock resolution engine.

Important: The Kafka generator requires a running Apache Kafka cluster. The generated server connects to it as a consumer — it does not replace or emulate a Kafka broker. Mocks for Kafka must be created manually through the Mockarty UI or API.

Provisioning a real Kafka cluster

For local development, the fastest options are:

• Docker Compose — a one-line KRaft-mode Kafka container is enough:

  # docker-compose.kafka.yml
  services:
    kafka:
      image: bitnami/kafka:3.7
      ports:
        - "9092:9092"
      environment:
        KAFKA_CFG_NODE_ID: "1"
        KAFKA_CFG_PROCESS_ROLES: "broker,controller"
        KAFKA_CFG_LISTENERS: "PLAINTEXT://:9092,CONTROLLER://:9093"
        KAFKA_CFG_ADVERTISED_LISTENERS: "PLAINTEXT://localhost:9092"
        KAFKA_CFG_CONTROLLER_QUORUM_VOTERS: "1@localhost:9093"
        KAFKA_CFG_CONTROLLER_LISTENER_NAMES: "CONTROLLER"
        KAFKA_CFG_LISTENER_SECURITY_PROTOCOL_MAP: "CONTROLLER:PLAINTEXT,PLAINTEXT:PLAINTEXT"
        ALLOW_PLAINTEXT_LISTENER: "yes"
  

  Run with docker compose -f docker-compose.kafka.yml up -d and use localhost:9092 in the generator config.

• Testcontainers — for CI suites, wrap the Kafka container in your test setup (see testcontainers-go Kafka module). The adapter receives the dynamically allocated address.

• Existing dev cluster — point the generator at any reachable Kafka cluster; the generated server only needs network access plus topic ACLs for the consumer group it joins.

Configuration

{
  "server": {
    "name": "my-kafka-server",
    "version": "1.0.0"
  },
  "config": {
    "namespace": "sandbox",
    "brokers": ["localhost:9092"],
    "consumerGroup": "mockarty-consumer",
    "autoCommit": true,
    "commitInterval": 5,
    "cacheEnabled": false,
    "serverName": "my-kafka-server"
  },
  "topics": [
    {
      "name": "orders",
      "eventName": "order-created",
      "outputTopic": "order-results"
    },
    {
      "name": "payments",
      "eventName": "payment-processed"
    }
  ]
}

Configuration fields:

Usage

# Generate server
mockarty-server-generator kafka \
  -input kafka-server.json \
  -output kafka_server.go \
  -package main \
  -server-name my-kafka-server

Build and Run

# Build (offline, vendored)
go build -mod=vendor -o kafka_server .

# Run
HTTP_PORT=8080 \
HTTP_ADMIN_BASE_URL=http://localhost:5770 \
NAMESPACE=sandbox \
./kafka_server

Features

• Connects to a real Kafka cluster as a consumer (Sarama library)
• Admin UI at /ui with dashboard and message viewer
• Built-in producer for sending test messages
• Mock resolution via POST /mock/findKafka on the HTTP node

RabbitMQ Generator

Generates a RabbitMQ adapter server that connects to a real RabbitMQ cluster, consumes messages from specified queues, and resolves mock responses via the Mockarty HTTP node.

Important: The RabbitMQ generator requires a running RabbitMQ instance. The generated server connects to it as a consumer — it does not replace or emulate a RabbitMQ broker. Mocks for RabbitMQ must be created manually through the Mockarty UI or API.

Provisioning a real RabbitMQ instance

For local development:

• Docker Compose — single-node RabbitMQ with the management UI:

  # docker-compose.rabbitmq.yml
  services:
    rabbitmq:
      image: rabbitmq:3.13-management
      ports:
        - "5672:5672"   # AMQP
        - "15672:15672" # Management UI
      environment:
        RABBITMQ_DEFAULT_USER: guest
        RABBITMQ_DEFAULT_PASS: guest
  

  Run with docker compose -f docker-compose.rabbitmq.yml up -d and use amqp://guest:guest@localhost:5672/ as the URL.

• Testcontainers — see testcontainers-go RabbitMQ module for ephemeral instances in CI.

• Existing dev RabbitMQ — any reachable instance works; the adapter needs a user with permissions on the target vhost.

Configuration

{
  "server": {
    "name": "my-rabbitmq-server",
    "version": "1.0.0"
  },
  "config": {
    "namespace": "sandbox",
    "url": "amqp://guest:guest@localhost:5672/",
    "prefetchCount": 1,
    "cacheEnabled": false,
    "serverName": "my-rabbitmq-server"
  },
  "queues": [
    {
      "name": "orders-queue",
      "eventName": "order-received",
      "exchange": "orders",
      "routingKey": "orders.#"
    },
    {
      "name": "notifications-queue",
      "eventName": "notification-received"
    }
  ]
}

Configuration fields:

The RABBITMQ_URL environment variable can override config.url at runtime. The management API URL is auto-derived (port 15672).

Usage

# Generate server
mockarty-server-generator rabbitmq \
  -input rabbitmq-server.json \
  -output rabbitmq_server.go \
  -package main \
  -server-name my-rabbitmq-server

Build and Run

# Build (offline, vendored)
go build -mod=vendor -o rabbitmq_server .

# Run
HTTP_PORT=8080 \
HTTP_ADMIN_BASE_URL=http://localhost:5770 \
NAMESPACE=sandbox \
RABBITMQ_URL=amqp://guest:guest@localhost:5672/ \
./rabbitmq_server

Features

• Connects to a real RabbitMQ instance as a consumer (AMQP 0.9.1)
• Admin UI at /ui with dashboard and message viewer
• Built-in publisher for sending test messages
• Mock resolution via POST /mock/findRabbitMQ on the HTTP node

SSE Generator

Generates a Server-Sent Events adapter server from a JSON/YAML configuration. The generated server provides SSE endpoints that resolve mock responses via the Mockarty HTTP node.

Important: Mocks for SSE must be created manually through the Mockarty UI or API.

Configuration

{
  "server": {
    "name": "my-sse-server",
    "version": "1.0.0"
  },
  "config": {
    "namespace": "sandbox",
    "sseEndpoint": "/sse",
    "port": 8090,
    "cacheEnabled": false
  },
  "events": [
    {
      "name": "notifications",
      "path": "/events/notifications",
      "description": "User notification events"
    },
    {
      "name": "heartbeat",
      "path": "/events/heartbeat",
      "description": "Keepalive heartbeat"
    }
  ]
}

Usage

# Generate server
mockarty-server-generator sse \
  -input sse-server.json \
  -output sse_server.go \
  -package main

# With path prefix
mockarty-server-generator sse \
  -input sse-server.json \
  -output sse_server.go \
  -package main \
  -path-prefix "v1/streams"

Running

HTTP_PORT=8080 ./sse_server

Features

• SSE streams with text/event-stream content type
• Admin UI at /ui with SSE Viewer (real-time event stream monitor)
• Path prefix support for route organization
• Mock resolution via SSERequestContext (event path + event name)

Socket Generator

Generates WebSocket, TCP, and UDP adapter servers from a JSON/YAML configuration. Each socket type uses a different Go template for the generated code. The generated server resolves mock responses via the Mockarty HTTP node.

Important: Mocks for Socket must be created manually through the Mockarty UI or API.

WebSocket Configuration

{
  "server": {
    "name": "my-ws-server",
    "version": "1.0.0"
  },
  "config": {
    "httpAdminHost": "localhost",
    "httpAdminPort": "5770",
    "namespace": "sandbox",
    "socketType": "websocket",
    "socketPort": 8081,
    "messageFormat": "json",
    "readTimeout": 30,
    "writeTimeout": 30
  }
}

TCP / UDP Configuration

{
  "server": {
    "name": "my-tcp-server",
    "version": "1.0.0"
  },
  "config": {
    "httpAdminHost": "localhost",
    "httpAdminPort": "5770",
    "namespace": "sandbox",
    "socketType": "tcp",
    "socketPort": 8080,
    "messageFormat": "json",
    "readTimeout": 30,
    "writeTimeout": 30
  },
  "messageHandlers": [
    {
      "pattern": ".*",
      "handler": "generic"
    }
  ]
}

Replace "socketType": "tcp" with "socketType": "udp" for UDP servers.

Usage

# Generate WebSocket server
mockarty-server-generator socket \
  -input ws-server.json \
  -output socket_server.go \
  -package main \
  -server-name my-ws-server

# Generate TCP server
mockarty-server-generator socket \
  -input tcp-server.json \
  -output socket_server.go \
  -package main

Running

HTTP_PORT=8080 ./socket_server

Features

• WebSocket: Bidirectional communication with embedded WebSocket Console at /ui
• TCP: Raw TCP socket server
• UDP: Raw UDP socket server
• Mock resolution via SocketRequestContext with serverName and eventName

SMTP Generator

Generates an SMTP adapter server from a JSON/YAML configuration that receives emails and resolves responses via the Mockarty HTTP node.

Important: Mocks for SMTP must be created manually through the Mockarty UI or API.

Configuration

{
  "server": {
    "name": "my-smtp-server",
    "version": "1.0.0"
  },
  "config": {
    "namespace": "sandbox",
    "smtpPort": 2525,
    "serverName": "my-smtp-server",
    "cacheEnabled": false
  }
}

Usage

# Generate server
mockarty-server-generator smtp \
  -input smtp-server.json \
  -output smtp_server.go \
  -package main \
  -server-name my-smtp-server

Build and Run

# Build (offline, vendored)
go build -mod=vendor -o smtp_server .

# Run
HTTP_PORT=8080 \
HTTP_ADMIN_BASE_URL=http://localhost:5770 \
NAMESPACE=sandbox \
./smtp_server

Features

• SMTP server accepting email messages
• Admin UI at /ui with message viewer
• Mock resolution via POST /mock/findSmtp on the HTTP node
• Configurable SMTP port (default: 2525)

HAR Import

HAR (HTTP Archive) files can be imported to create mocks and API test collections. This feature is available through the Mockarty Web UI, not the server generator CLI.

Import via Web UI

1. Open the API Tester page in Mockarty
2. Click Import and select HAR
3. Upload a HAR file or provide a URL
4. Mockarty parses the HAR entries and creates:
   • An API Tester collection with all requests
   • Auto-generated test scripts for each request (status checks, content-type, headers, JSON structure validation)
5. Static assets (CSS, JS, images, fonts) are automatically filtered out

Features

• URL replacement system rewrites base URLs to /stubs/{namespace}/path format
• Handles protocol-relative URLs, host-only URLs, query params, and fragments
• Replaces URLs in JSON values, HTML content, and headers

Smart Merge Strategy

The server generator implements intelligent mock update logic that is used by default when mocks already exist.

Default Behavior: Smart Merge

When you run the generator against a spec that already has mocks in Mockarty:

• Preserves user customizations (manually added response payloads, conditions, priorities)
• Updates the schema (adds new required fields, removes fields deleted from the spec)
• Supports rollback — if the spec reverts a change, the generator removes previously added fields

Force Update (-force-update)

Replaces everything from the spec. Use with caution — this discards all manual customizations.

How Merge Works

Payload merge — recursively merges response objects and arrays:

• Adds new required fields from the spec
• Removes fields that are no longer in the spec
• Preserves user values for existing fields

Condition merge — intelligently merges request conditions:

• Preserves user-configured assertions
• Adds new fields from the spec as any conditions (allows any value)
• Removes conditions for deleted fields

Example

Imagine you have an OpenAPI spec with a /users endpoint, and you’ve manually added a condition $.body.role == "admin" to the mock. When you re-run the generator with an updated spec:

• Smart merge (default): Your role == "admin" condition is preserved. New fields from the spec are added as any conditions.
• Force update: Your condition is replaced with auto-generated ones from the spec.

Orchestrator Mode

The server generator includes an orchestrator mode — a web server with REST API for managing multiple generated servers. The orchestrator handles server generation, lifecycle management, health monitoring, and state persistence.

mockarty-server-generator orchestrator [flags]

Orchestrator Flags

Coordinator Integration Flags

For distributed deployments, the orchestrator can register with a Mockarty coordinator:

Usage

# Basic orchestrator
mockarty-server-generator orchestrator \
  -api-token mk_your_token \
  -http-admin-base-url http://localhost:5770

# With custom port range and data directory
mockarty-server-generator orchestrator \
  -api-token mk_your_token \
  -port 7770 \
  -data-dir /var/lib/mockarty-orchestrator \
  -port-min 9000 \
  -port-max 9500

# With coordinator integration
mockarty-server-generator orchestrator \
  -api-token mk_your_token \
  -coordinator-addr coordinator.example.com:5773 \
  -integration-token mki_your_integration_token \
  -coordinator-tls

REST API

Server management:

Batch operations:

Cache management:

Other:

Generation Request Example

curl -X POST http://localhost:8888/api/servers/generate \
  -H "Content-Type: application/json" \
  -d '{
    "type": "openapi",
    "name": "petstore-api",
    "input": "/path/to/petstore.yaml",
    "namespace": "sandbox",
    "group": "development",
    "createMocks": true,
    "apiToken": "mk_your_token",
    "tags": ["v3", "test"]
  }'

Response:

{
  "jobId": "abc123",
  "status": "pending"
}

Poll job status:

curl http://localhost:8888/api/jobs/abc123

{
  "jobId": "abc123",
  "status": "completed",
  "progress": 100,
  "serverId": "petstore-api-xyz"
}

Key Features

• Async generation — long-running builds don’t block; track progress via job ID
• Health monitoring — background health checks every 30 seconds
• Port management — auto-allocates ports from configurable range
• State persistence — saves/restores via JSON files in data directory
• Event bus — decoupled SSE broadcasts for real-time UI updates
• Server groups — organize servers by environment or purpose
• Cleanup — auto-removes orphaned binaries and stale servers

Experimental UI

The experimental UI mode wraps the orchestrator with a web-based management interface that includes session authentication.

mockarty-server-generator experimental-ui [flags]

Flags

Inherits the base orchestrator flags (-port, -data-dir, -log-level, -api-token, -http-admin-base-url, -port-min, -port-max), plus:

Usage

mockarty-server-generator experimental-ui \
  -api-token mk_your_token \
  -port 8888 \
  -username admin \
  -password my_secure_password \
  -http-admin-base-url http://localhost:5770

The web UI will be available at http://localhost:8888. After login, you can:

• Generate new servers from specs (file upload or URL)
• Start, stop, restart, and monitor servers
• View server logs and metrics
• Manage server groups
• Monitor real-time events

Note: The experimental-ui mode adds session-based authentication (login/logout) on top of the orchestrator functionality, while the orchestrator mode exposes the API without authentication (designed for programmatic access or integration with an external auth layer). The orchestrator mode additionally supports coordinator integration flags for distributed deployments.

Generated Server Environment Variables

Common to All Generated Servers

Protocol-Specific Variables

Generated Server UI and Caching

Every generated server comes with a built-in web interface and caching system. These features require no additional configuration — they are embedded in the generated binary.

Embedded Web UI

Each protocol has a specialized admin UI accessible at /ui (or /swagger/ for OpenAPI):

Common Endpoints (All Servers)

High-Performance Caching for Load Testing

Generated servers include an optional high-performance response cache (based on bigcache, zero GC pressure). When enabled, the server caches mock responses and returns them without calling the Mockarty node, dramatically reducing latency.

This is designed for load/performance testing scenarios where you need the generated server to handle thousands of requests per second without overloading the Mockarty admin node.

Enable at generation time:

mockarty-server-generator openapi \
  -input ./api.yaml \
  -output server.go \
  -package main \
  -cache-perf-enable

Or enable at runtime via API:

# Enable caching on a running server
curl -X POST http://localhost:8080/cache/enable

# Check cache stats
curl http://localhost:8080/cache/stats

# Clear cache (e.g., after mock changes)
curl -X POST http://localhost:8080/cache/clear

# Disable caching
curl -X POST http://localhost:8080/cache/disable

Environment variables for cache tuning:

Typical load testing workflow:

1. Generate server and create mocks as usual
2. Configure your desired mock responses in Mockarty UI
3. Enable caching: curl -X POST http://server:8080/cache/enable
4. Run your load test (k6, JMeter, wrk, etc.) against the generated server
5. Cache serves responses in microseconds — no database or network calls
6. After testing, disable caching: curl -X POST http://server:8080/cache/disable

Output Structure & Offline Build

What Gets Generated

When you run the generator with -output and -package, it creates a complete Go project:

petstore-server/
├── server.go              # Generated server code
├── go.mod                 # Go module definition
├── go.sum                 # Dependency checksums
├── vendor/                # ALL dependencies vendored (no internet needed!)
├── assets/                # Swagger UI / GraphQL Playground JS, CSS
└── webfonts/              # Font Awesome icons

Building & Running

Generated servers include vendored dependencies, so they can be built completely offline:

cd petstore-server

# Build (no internet required!)
go build -mod=vendor -o server .

# Run
HTTP_PORT=8080 \
HTTP_ADMIN_BASE_URL=http://localhost:5770 \
NAMESPACE=sandbox \
./server

Vendored Dependencies

The server generator binary includes an embedded vendorfs bundle containing all Go dependencies, UI assets (Swagger UI, GraphQL Playground, Font Awesome), and module files. This means:

• No go mod download needed after generation
• Works in air-gapped environments
• Consistent builds regardless of network access

Docker Build

Containerizing the Generator (Recommended First Step)

The simplest approach: run the generator inside Docker with volume mounts. You pass in your spec file and get a ready-to-run binary or a complete Go project on the host.

Dockerfile for the generator tool:

FROM golang:1.26-alpine
RUN apk add --no-cache git ca-certificates
COPY mockarty-server-generator /usr/local/bin/
ENTRYPOINT ["mockarty-server-generator"]

# Build the generator image (once)
docker build -t mockarty-generator:latest -f Dockerfile.generator .

# Generate + build a server in one step
# Input: ./api/openapi.yaml on the host
# Output: ./output/ directory with the built binary
docker run --rm \
  -v $(pwd)/api:/specs:ro \
  -v $(pwd)/output:/output \
  mockarty-generator:latest openapi \
    -input /specs/openapi.yaml \
    -output /output/server.go \
    -package main

# Now build the binary (Go is inside the container)
docker run --rm \
  -v $(pwd)/output:/app \
  -w /app \
  golang:1.26-alpine \
  go build -mod=vendor -o server .

# The binary is now at ./output/server — run it directly
HTTP_ADMIN_BASE_URL=http://localhost:5770 ./output/server

All-in-one: generate + build + get binary:

docker run --rm \
  -v $(pwd)/api:/specs:ro \
  -v $(pwd)/output:/output \
  mockarty-generator:latest sh -c '\
    mockarty-server-generator openapi \
      -input /specs/openapi.yaml \
      -output /tmp/server/server.go \
      -package main && \
    cd /tmp/server && \
    go build -mod=vendor -o /output/server .'

After this, ./output/server is a static Linux binary you can run anywhere (or copy into a minimal Docker image).

Generate + create mocks in Mockarty simultaneously:

docker run --rm \
  -v $(pwd)/proto:/specs:ro \
  -v $(pwd)/output:/output \
  --network host \
  mockarty-generator:latest grpc \
    -input /specs/ \
    -output /output/server.go \
    -package main \
    -create-mocks \
    -api-token mk_your_token \
    -http-admin-base-url http://localhost:5770 \
    -namespace sandbox \
    -server-name my-grpc-service

Tip: Use --network host so the container can reach the Mockarty admin node on localhost. In Docker Compose, use the service name instead (e.g., http://mockarty:5770).

Containerizing the Generated Server

Once you have a generated Go project, containerize it with a multi-stage Dockerfile:

Create a Dockerfile in the generated server directory:

# Stage 1: Build
FROM golang:1.26-alpine AS builder
WORKDIR /app
COPY . .
RUN go build -mod=vendor -o server .

# Stage 2: Run
FROM alpine:3.20
RUN apk add --no-cache ca-certificates
COPY --from=builder /app/server /usr/local/bin/server
EXPOSE 8080
ENV HTTP_PORT=8080
ENV HTTP_ADMIN_BASE_URL=http://mockarty:5770
ENV NAMESPACE=sandbox
ENTRYPOINT ["server"]

Build and Run

# Build the image
docker build -t my-mock-server:latest ./petstore-server/

# Run
docker run -d \
  --name petstore-mock \
  -p 8080:8080 \
  -e HTTP_ADMIN_BASE_URL=http://mockarty-admin:5770 \
  -e NAMESPACE=sandbox \
  my-mock-server:latest

gRPC Server Dockerfile

For gRPC servers, expose both the HTTP admin and gRPC ports:

FROM golang:1.26-alpine AS builder
WORKDIR /app
COPY . .
RUN go build -mod=vendor -o server .

FROM alpine:3.20
RUN apk add --no-cache ca-certificates
COPY --from=builder /app/server /usr/local/bin/server
EXPOSE 8080 4770
ENV HTTP_PORT=8080
ENV GRPC_PORT=4770
ENV HTTP_ADMIN_BASE_URL=http://mockarty:5770
ENV NAMESPACE=sandbox
ENTRYPOINT ["server"]

docker run -d \
  -p 8080:8080 \
  -p 4770:4770 \
  -e HTTP_ADMIN_BASE_URL=http://mockarty-admin:5770 \
  my-grpc-server:latest

SOAP Server Dockerfile

SOAP servers use two ports (SOAP endpoint + admin UI):

FROM golang:1.26-alpine AS builder
WORKDIR /app
COPY . .
RUN go build -mod=vendor -o server .

FROM alpine:3.20
RUN apk add --no-cache ca-certificates
COPY --from=builder /app/server /usr/local/bin/server
EXPOSE 8080 8081
ENV HTTP_PORT=8080
ENV ADMIN_PORT=8081
ENV HTTP_ADMIN_BASE_URL=http://mockarty:5770
ENTRYPOINT ["server"]

Docker Compose: Generated Server + Mockarty

version: "3.8"
services:
  postgres:
    image: postgres:17-alpine
    environment:
      POSTGRES_DB: mockarty
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: postgres
    volumes:
      - pgdata:/var/lib/postgresql/data

  mockarty:
    image: mockarty/mockarty:latest
    ports:
      - "5770:5770"
    environment:
      DB_DSN: "postgresql://postgres:postgres@postgres:5432/mockarty?sslmode=disable"
    depends_on:
      - postgres

  petstore-mock:
    build: ./petstore-server
    ports:
      - "8080:8080"
    environment:
      HTTP_PORT: "8080"
      HTTP_ADMIN_BASE_URL: "http://mockarty:5770"
      NAMESPACE: "sandbox"
    depends_on:
      - mockarty

volumes:
  pgdata:

# Start everything
docker compose up -d

# Import mocks (first time only)
./mockarty-server-generator openapi \
  -input ./api/openapi.yaml \
  -create-mocks \
  -api-token mk_your_token \
  -namespace sandbox

# Test
curl http://localhost:8080/pet/1

One-Step CI Build (without Go locally)

If you don’t have Go installed locally, build inside Docker:

# Generate code (no Go needed for this step)
./mockarty-server-generator openapi \
  -input ./api/openapi.yaml \
  -output ./server/server.go \
  -package main

# Build inside Docker (Go is in the builder stage)
docker build -t my-server:latest ./server/

CI/CD Pipeline Examples

GitHub Actions

name: Deploy Mock Server

on:
  push:
    branches: [main]
    paths: ['api/**']

jobs:
  deploy-mocks:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Download Server Generator
        run: |
          curl -L -o mockarty-server-generator \
            https://releases.mockarty.ru/latest/linux-amd64/mockarty-server-generator
          chmod +x mockarty-server-generator

      - name: Generate server + create mocks
        run: |
          ./mockarty-server-generator openapi \
            -input ./api/openapi.yaml \
            -output ./mock-server/server.go \
            -package main \
            -create-mocks \
            -api-token ${{ secrets.MOCKARTY_API_TOKEN }} \
            -http-admin-base-url ${{ vars.MOCKARTY_URL }} \
            -namespace ${{ github.ref_name }} \
            -tags "ci,commit-${{ github.sha }}"

      - name: Build Docker image
        run: |
          cat > mock-server/Dockerfile << 'DOCKERFILE'
          FROM golang:1.26-alpine AS builder
          WORKDIR /app
          COPY . .
          RUN go build -mod=vendor -o server .
          FROM alpine:3.20
          RUN apk add --no-cache ca-certificates
          COPY --from=builder /app/server /usr/local/bin/server
          EXPOSE 8080
          ENTRYPOINT ["server"]
          DOCKERFILE
          docker build -t mock-server:${{ github.sha }} ./mock-server/

      - name: Push to registry
        run: |
          docker tag mock-server:${{ github.sha }} registry.example.com/mock-server:latest
          docker push registry.example.com/mock-server:latest

GitLab CI

stages:
  - generate
  - build
  - deploy

generate-mocks:
  stage: generate
  image: golang:1.26-alpine
  script:
    - wget -O /usr/local/bin/mockarty-server-generator https://releases.mockarty.ru/latest/linux-amd64/mockarty-server-generator
    - chmod +x /usr/local/bin/mockarty-server-generator
    - mockarty-server-generator openapi
        -input ./api/openapi.yaml
        -output ./generated-server/server.go
        -package main
        -create-mocks
        -api-token $MOCKARTY_TOKEN
        -http-admin-base-url $MOCKARTY_URL
        -namespace $CI_COMMIT_REF_SLUG
  artifacts:
    paths:
      - generated-server/

build-image:
  stage: build
  image: docker:latest
  services:
    - docker:dind
  script:
    - cd generated-server
    - |
      cat > Dockerfile << 'EOF'
      FROM golang:1.26-alpine AS builder
      WORKDIR /app
      COPY . .
      RUN go build -mod=vendor -o server .
      FROM alpine:3.20
      RUN apk add --no-cache ca-certificates
      COPY --from=builder /app/server /usr/local/bin/server
      EXPOSE 8080
      ENTRYPOINT ["server"]
      EOF
    - docker build -t $CI_REGISTRY_IMAGE/mock-server:$CI_COMMIT_SHORT_SHA .
    - docker push $CI_REGISTRY_IMAGE/mock-server:$CI_COMMIT_SHORT_SHA

deploy:
  stage: deploy
  script:
    - kubectl set image deployment/mock-server mock-server=$CI_REGISTRY_IMAGE/mock-server:$CI_COMMIT_SHORT_SHA

API-First Workflow in CI

Use the generator to keep mocks in sync with your API spec on every PR:

# 1. Spec changes trigger CI
# 2. Generator updates mocks (smart merge preserves customizations)
./mockarty-server-generator openapi \
  -input ./api/openapi.yaml \
  -create-mocks \
  -api-token $MOCKARTY_TOKEN \
  -namespace $BRANCH_NAME \
  -tags "pr-$PR_NUMBER"

# 3. Frontend team tests against updated mocks immediately
# 4. No code changes needed — mocks update automatically from spec

Mock Examples

These examples show how to manually create mocks via the Mockarty API for use with generated servers. For spec-based generators (OpenAPI, gRPC, MCP, GraphQL, SOAP), mocks can also be auto-created using the -create-mocks flag. For config-based adapters (Kafka, RabbitMQ, SSE, Socket, SMTP), mocks must always be created manually.

MCP Mock

{
  "id": "mcp-tool-mock",
  "namespace": "sandbox",
  "mcp": {
    "serverName": "example-mcp-server",
    "method": "tool_name",
    "conditions": [
      {
        "path": "$.param1",
        "assertAction": "equals",
        "value": "test"
      }
    ]
  },
  "response": {
    "statusCode": 200,
    "payload": {
      "result": "success"
    }
  }
}

gRPC Mock

{
  "id": "grpc-method-mock",
  "namespace": "sandbox",
  "grpc": {
    "service": "UserService",
    "method": "GetUser",
    "conditions": [
      {
        "path": "$.id",
        "assertAction": "equals",
        "value": "123"
      }
    ]
  },
  "response": {
    "statusCode": 0,
    "payload": {
      "id": "123",
      "name": "John Doe"
    }
  }
}

GraphQL Mock

{
  "id": "graphql-query-mock",
  "namespace": "sandbox",
  "graphql": {
    "operation": "query",
    "field": "GetUser"
  },
  "response": {
    "statusCode": 200,
    "payload": {
      "data": {
        "user": {
          "id": "1",
          "name": "$.fake.Name",
          "email": "$.fake.Email"
        }
      }
    }
  }
}

Kafka Mock

{
  "id": "kafka-orders-mock",
  "namespace": "sandbox",
  "kafka": {
    "topic": "orders",
    "serverName": "my-kafka-server"
  },
  "response": {
    "statusCode": 200,
    "payload": {
      "orderId": "$.fake.UUID",
      "status": "processed"
    }
  }
}

SOAP Mock

{
  "id": "soap-getuser-mock",
  "namespace": "sandbox",
  "soap": {
    "soapAction": "GetUser",
    "path": "/ws/users"
  },
  "response": {
    "statusCode": 200,
    "payload": "<GetUserResponse><Name>John</Name></GetUserResponse>"
  }
}

RabbitMQ Mock

{
  "id": "rabbitmq-orders-mock",
  "namespace": "sandbox",
  "rabbitmq": {
    "queue": "orders.queue",
    "exchange": "orders.exchange",
    "serverName": "my-rabbitmq-server"
  },
  "response": {
    "statusCode": 200,
    "payload": {
      "orderId": "$.fake.UUID",
      "status": "received"
    }
  }
}

SSE Mock

{
  "id": "sse-events-mock",
  "namespace": "sandbox",
  "sse": {
    "path": "/events",
    "eventName": "notification"
  },
  "response": {
    "statusCode": 200,
    "payload": {
      "type": "alert",
      "message": "$.fake.Sentence"
    }
  }
}

Socket (WebSocket) Mock

{
  "id": "ws-message-mock",
  "namespace": "sandbox",
  "socket": {
    "serverName": "my-ws-server",
    "eventName": "message"
  },
  "response": {
    "statusCode": 200,
    "payload": {
      "echo": "$.req.data",
      "timestamp": "$.fake.UnixTime"
    }
  }
}

Limitations

General

1. Mockarty HTTP node required — generated servers cannot work without a running Mockarty instance (admin or resolver node)
2. Namespace isolation — all mocks must be in the specified namespace
3. Network accessibility — Mockarty HTTP node must be reachable from the machine running the generated server
4. License validation — -create-mocks mode and orchestrator/experimental-ui require a valid license with mock feature

Protocol-Specific

Mockarty Server Generator — unified code generation for 8 protocols and 2 message brokers from a single binary.

See Also

• Integrations Guide — Set up resolver nodes, runner agents, and the API-first workflow
• Installation & Deployment — Docker Compose examples with generated servers
• Faker Reference — All Faker functions available in mock responses
• JsonPath Guide — Request data extraction and response interpolation
• API Reference — REST API for programmatic mock management