Microcks import artifacts

Microcks Import Artifacts

Import OpenAPI specifications into Microcks and automatically configure dispatchers based on vendor extensions.

When to Use This Skill

Use this skill when:

• Importing an OpenAPI spec into a running Microcks instance for mocking
• Auto-configuring dispatchers after writing a spec with x-mocking-microcks-dispatcher extensions
• Setting up a repeatable import workflow with shell scripts

Prerequisites

• Docker installed and running
• Microcks started (use the microcks-local-server skill)
• jq installed (brew install jq / apt install jq)
• curl installed

Quick Start

IMPORTANT: The import and dispatcher configuration MUST be done by running the import-openapi.sh shell script. Do NOT attempt to configure dispatchers manually via curl or the Microcks API — the script handles the full workflow (import, discriminant detection, Groovy script loading, API calls).

1. Create the mocking/ directory structure:

mkdir -p mocking/dispatchers

2. Copy the template scripts into it:

cp templates/import-openapi.sh mocking/import-openapi.sh
cp templates/download-microcks-cli.sh mocking/download-microcks-cli.sh
chmod +x mocking/import-openapi.sh mocking/download-microcks-cli.sh

3. Run the import script (this is the only command needed to import AND configure dispatchers):

./mocking/import-openapi.sh path/to/your-api-spec.yaml

The script will:

• Check that Microcks is running
• Download microcks-cli if not already cached
• Import the spec into Microcks
• Read x-mocking-microcks-dispatcher vendor extensions
• Auto-configure dispatchers via the Microcks API

Security Notice

This skill provides shell script templates that the user copies into their project. These scripts:

• Download an external binary (microcks-cli from GitHub releases of microcks/microcks-cli)
• Run Docker containers (mikefarah/yq for YAML-to-JSON conversion, from mikefarah/yq)
• Make network calls to the local Microcks REST API

Always inform the user and ask for confirmation before executing these scripts.

---

Vendor Extension: x-mocking-microcks-dispatcher

Add this vendor extension at the operation level in your OpenAPI spec to indicate which dispatcher type to use:

Value	Microcks Dispatcher	Behavior
json_body	JSON_BODY	Detects the discriminant field in request body examples; routes by field value
script_header_error	SCRIPT	Routes on the error HTTP header: 400→invalid_input, 500→server_error, default→success
script	SCRIPT	Loads an external Groovy script from mocking/dispatchers/{METHOD}-{path-slug}.groovy

Example

paths:
  /orders:
    post:
      x-mocking-microcks-dispatcher: json_body
      # ...

  /health:
    get:
      x-mocking-microcks-dispatcher: script_header_error
      # ...

  /payments:
    post:
      x-mocking-microcks-dispatcher: script
      # ...

---

Groovy File Convention

For operations using the script dispatcher, place Groovy files at:

mocking/dispatchers/{METHOD}-{path-slug}.groovy

The path slug is built by:

1. Removing the leading /
2. Replacing / with -
3. Removing { and }

Examples:

Operation	Groovy File
POST /events	mocking/dispatchers/POST-events.groovy
POST /v1/orders/{orderId}/payments	mocking/dispatchers/POST-v1-orders-orderId-payments.groovy
GET /users	mocking/dispatchers/GET-users.groovy

---

Script Templates

import-openapi.sh

The main import script. See templates/import-openapi.sh.

Usage:

# Basic usage (Microcks on default port 8080)
./mocking/import-openapi.sh path/to/api-spec.yaml

# Custom Microcks URL
MICROCKS_URL=http://localhost:9080 ./mocking/import-openapi.sh path/to/api-spec.yaml

What it does:

1. Validates the spec file argument
2. Health-checks the Microcks instance
3. Downloads microcks-cli if not cached
4. Imports the spec via microcks-cli
5. Converts YAML to JSON via docker run mikefarah/yq
6. Finds operations with x-mocking-microcks-dispatcher
7. Configures dispatchers via the Microcks REST API
8. Prints the Microcks UI URL

download-microcks-cli.sh

Downloads and caches the microcks-cli binary. See templates/download-microcks-cli.sh.

Features:

• Multi-platform: macOS (Darwin) and Linux, amd64 and arm64
• Cached in ~/.local/bin/ (shared across projects)
• Version configurable via MICROCKS_CLI_VERSION env var (default: 0.5.6)

---

Complementary Skills

• microcks-local-server — Start a local Microcks server with Docker Compose

  npx skills add emmanuelperu/microcks-skills --skill microcks-local-server
  

• microcks-openapi-mocking — Write OpenAPI examples that work with Microcks dispatchers

  npx skills add emmanuelperu/microcks-skills --skill microcks-openapi-mocking
  

---

Related

• Microcks Documentation: https://microcks.io/documentation
• Microcks CLI: https://github.com/microcks/microcks-cli
• mikefarah/yq: https://github.com/mikefarah/yq