microcks-openapi-mocking

Microcks OpenAPI Mocking

Help write and configure OpenAPI specifications with examples that work correctly in Microcks.

When to Use This Skill

Use this skill when:

• Writing or editing named examples in an OpenAPI spec for Microcks mocking
• Adding a new endpoint to an OpenAPI spec with multiple example scenarios (success, errors)
• Configuring a dispatcher to control how Microcks routes requests to different responses
• Debugging a mock response that isn't returning the expected data
• Setting up example pairing between request and response examples in OpenAPI

Core Rules

Microcks mocking depends on correct example pairing and dispatcher configuration. Here are the key rules:

Rule 1: Example Names Must Match Across Locations

Every named example in path/query parameters and request body must have a corresponding response example with the same name.

paths:
  /pets/{petId}:
    get:
      parameters:
        - name: petId
          examples:
            success:      # ← example name
              value: 1
            not_found:    # ← example name
              value: 999
      responses:
        '200':
          content:
            application/json:
              examples:
                success:    # ← same name
                  value: { id: 1, name: Fluffy }
        '404':
          content:
            application/json:
              examples:
                not_found:  # ← same name
                  value: { error: Not found }

Details: See example-pairing.md

Rule 2: No-Body Responses Need Content Block with value: null

Responses with no body (204, 304) must still have a content block with explicit value: null:

delete:
  responses:
    '204':
      description: Deleted
      content:
        application/json:
          examples:
            success:
              value: null  # ← Required for no-body responses

Rule 3: All Error Examples Need Input Examples