### Start Interactive Examples GUI with Docker

Source: https://docs.specmatic.io/features/external_examples

Execute this command to start the Specmatic interactive examples GUI using Docker. Ensure you have Docker installed and the necessary spec file in your current directory.

```bash
docker run --rm --network host -v "$(pwd):/usr/src/app" specmatic/enterprise examples interactive --spec-file "employee_details.yaml"
```

--------------------------------

### Start Interactive Example Generation

Source: https://docs.specmatic.io/features/json_schema/discriminator

Launches the interactive example generation server. Ensure you have the OpenAPI specification file available.

```bash
specmatic examples interactive --spec-file=petstore.yaml
```

--------------------------------

### Start Interactive Examples GUI with Java

Source: https://docs.specmatic.io/features/external_examples

Execute this command to start the Specmatic interactive examples GUI using a Java JAR file. Ensure the specmatic-openapi.jar is available and the spec file is in your current directory.

```bash
java -jar specmatic-openapi.jar examples interactive --spec-file employee_details.yaml
```

--------------------------------

### Specify Example Directories via CLI Argument

Source: https://docs.specmatic.io/supported_protocols/graphql

Uses the --examples argument in the CLI to specify custom directories for example data.

```bash
--examples=./custom-examples --examples=./more-examples
```

--------------------------------

### Spin up a mock server using Specmatic CLI

Source: https://docs.specmatic.io/getting_started/cli_quick_start

Run this command to start a mock server directly using the Specmatic CLI. Ensure Specmatic is installed and accessible in your PATH.

```bash
specmatic mock service.yaml
```

--------------------------------

### Initialize Mock Server in Kotlin Test Setup

Source: https://docs.specmatic.io/contract_driven_development/service_virtualization

Use the createStub() utility in your test's setup method to programmatically start the Specmatic mock server. It automatically loads contract specifications from configuration files.

```kotlin
import io.specmatic.stub.ContractStub
import io.specmatic.test.SpecmaticContractTest
import org.junit.jupiter.api.BeforeAll

class YourTest: SpecmaticContractTest {
  companion object {
    private val mock: ContractStub

    @BeforeAll
    @JvmStatic
    fun setUp() {
      mock = createStub()
    }
  }
}
```

--------------------------------

### Spin up a mock server using npx

Source: https://docs.specmatic.io/getting_started/cli_quick_start

Execute this command to start a mock server using npx, which downloads and runs the Specmatic package without global installation. This is useful for projects with specific Specmatic version requirements.

```bash
npx specmatic mock service.yaml
```

--------------------------------

### Start Specmatic Mock in Strict Mode (npm)

Source: https://docs.specmatic.io/contract_driven_development/service_virtualization

Use this command to start the Specmatic mock server in strict mode when installed via npm.

```bash
npx specmatic mock --strict  
```

--------------------------------

### Set EXAMPLES_DIR System Property for Examples

Source: https://docs.specmatic.io/supported_protocols/graphql

Sets the EXAMPLES_DIR system property to specify custom example directories programmatically.

```java
System.setProperty("EXAMPLES_DIR", "./custom-examples,./more-examples");
```

--------------------------------

### GraphQL Example Request and Response

Source: https://docs.specmatic.io/supported_protocols/graphql

Provides an example query and its corresponding response for finding available products.

```yaml
request:
  body: |
    query {
      findAvailableProducts(type: gadget, pageSize: 10) {
        id
        name
        inventory
        type
      }
    }
response: [
    {
        "id": "10",
        "name": "The Almanac",
        "inventory": 10,
        "type": "book"
    },
    {
        "id": "20",
        "name": "iPhone",
        "inventory": 15,
        "type": "gadget"
    }
]
```

--------------------------------

### Example Request: Product by ID

Source: https://docs.specmatic.io/supported_protocols/graphql

An example request to retrieve product details by its ID.

```yaml
request:
  body: |
    query {
      productById(id: "10") {
        id
        name
        type
      }
    }
response: {
    "id": "10",
    "name": "The Almanac",
    "type": "book"
}
```

--------------------------------

### Start Specmatic Mock Server (NPM)

Source: https://docs.specmatic.io/contract_driven_development/service_virtualization

Starts the Specmatic mock server using the Node Package Manager.

```bash
npx specmatic mock  

```

--------------------------------

### Generate Dictionary from Examples using Docker

Source: https://docs.specmatic.io/features/dictionary

Executes the Specmatic Enterprise Docker image to generate a dictionary from the provided OpenAPI specification and examples. Ensure the examples folder is suffixed with '_examples'.

```bash
docker run --rm -v "$(pwd):/usr/src/app" specmatic/enterprise examples dictionary --spec-file employees.yaml  

```

--------------------------------

### Start Specmatic Mock Server (Docker Windows)

Source: https://docs.specmatic.io/contract_driven_development/service_virtualization

Starts the Specmatic mock server using Docker on Windows.

```bash
docker run -p 9000:9000 -v "${PWD}:/usr/src/app" specmatic/specmatic mock  

```

--------------------------------

### Specmatic Configuration for Example Directories

Source: https://docs.specmatic.io/supported_protocols/grpc

Example configuration in `specmatic.yaml` to specify directories containing externalized gRPC example data. This allows Specmatic to locate and use custom test/stub data.

```yaml
version: 3
dependencies:
  services:
    - service:
        $ref: "#/components/services/yourService"
        runOptions:
          $ref: "#/components/runOptions/yourServiceMock"
        data:
          examples:
            - directories:
                - path/to/dir1
                - path/to/dir2
components:
  sources:
    yourContracts:
      git:
        url: https://your-central-contract-repo.com
        branch: main
  services:
    yourService:
      description: Your gRPC Service
      definitions:
        - definition:
            source:
              $ref: "#/components/sources/yourContracts"
            specs:
              - spec:
                  id: yourServiceSpec
                  path: /path/to/your/service.proto
  runOptions:
    yourServiceMock:
      protobuf:
        type: mock
        specs:
          - spec:
              id: yourServiceSpec
              host: localhost
              port: 9000
              importPaths:
                - ../
              protocVersion: 3.23.4
```

--------------------------------

### Specmatic v2 Configuration with Externalized Examples (YAML)

Source: https://docs.specmatic.io/references/configuration/test-configuration

Configure externalized example directories using the 'examples' key in specmatic.yaml for version 2. This allows Specmatic to pick up examples from specified paths for contract testing and service virtualization.

```yaml
version: 2  
contracts:  
  - git:  
      url: https://github.com/specmatic/specmatic-order-contracts.git  
    provides:  
      - io/specmatic/examples/store/openapi/product_search_bff_v4.yaml  
    consumes:  
      - io/specmatic/examples/store/openapi/api_order_v3.yaml  
examples:  
  - order_service/examples  
  - product_service/examples  

```

--------------------------------

### Start Specmatic Mock Server (Java JAR)

Source: https://docs.specmatic.io/contract_driven_development/service_virtualization

Starts the Specmatic mock server using the downloaded JAR file.

```java
java -jar specmatic.jar mock  

```

--------------------------------

### Start Specmatic Mock Server (Docker Linux/macOS)

Source: https://docs.specmatic.io/contract_driven_development/service_virtualization

Starts the Specmatic mock server using Docker on Linux or macOS.

```bash
docker run --network host -v "$(pwd):/usr/src/app" specmatic/specmatic mock  

```

--------------------------------

### Example Tool Schema

Source: https://docs.specmatic.io/getting_started/mcp_auto_test

This is an example schema for a tool named 'createUser'. It defines the expected input structure for the tool.

```json
{
  "name": "createUser",
  "description": "Creates a new user in the system",
  "inputSchema": {
    "type": "object",
    "properties": {
      "name": { "type": "string" },
      "age": { "type": "integer" },
      "address": {
        "type": "object",
        "properties": {
          "city": { "type": "string" },
          "zip": { "type": "string" }
        }
      }
    },
    "required": ["name", "age"]
  }
}
```

--------------------------------

### Specmatic v3 Configuration with Externalized Examples (JSON)

Source: https://docs.specmatic.io/references/configuration/test-configuration

Configure externalized example directories using the 'examples.commonExamples.directories' key in specmatic.json for version 3. This allows Specmatic to pick up examples from specified paths for contract testing and service virtualization.

```json
{
  "version": 3,
  "systemUnderTest": {
    "service": {
      "$ref": "#/components/services/productSearchBffV4",
      "runOptions": {
        "openapi": {
          "type": "mock",
          "host": "localhost",
          "port": 9000
        }
      }
    }
  },
  "dependencies": {
    "services": [
      {
        "service": {
          "$ref": "#/components/services/apiOrderV3",
          "runOptions": {
            "openapi": {
              "type": "mock",
              "host": "localhost",
              "port": 9001
            }
          }
        }
      }
    ]
  },
  "components": {
    "sources": {
      "specmaticOrderContracts": {
        "git": {
          "url": "https://github.com/specmatic/specmatic-order-contracts.git"
        }
      }
    },
    "services": {
      "productSearchBffV4": {
        "description": "Product Search BFF v4 (provider)",
        "definitions": [
          {
            "definition": {
              "source": {
                "$ref": "#/components/sources/specmaticOrderContracts"
              },
              "specs": [
                "io/specmatic/examples/store/openapi/product_search_bff_v4.yaml"
              ]
            }
          }
        ]
      },
      "apiOrderV3": {
        "description": "API Order V3 (consumer)",
        "definitions": [
          {
            "definition": {
              "source": {
                "$ref": "#/components/sources/specmaticOrderContracts"
              },
              "specs": [
                "io/specmatic/examples/store/openapi/api_order_v3.yaml"
              ]
            }
          }
        ]
      }
    },
    "examples": {
      "commonExamples": {
        "directories": [
          "order_service/examples",
          "product_service/examples"
        ]
      }
    }
  }
}

```

--------------------------------

### Specmatic v3 Configuration with Externalized Examples (YAML)

Source: https://docs.specmatic.io/references/configuration/test-configuration

Configure externalized example directories using the 'examples.commonExamples.directories' key in specmatic.yaml for version 3. This allows Specmatic to pick up examples from specified paths for contract testing and service virtualization.

```yaml
version: 3  
systemUnderTest:  
  service:  
    $ref: "#/components/services/productSearchBffV4"  
    runOptions:  
      openapi:  
        type: mock  
        host: localhost  
        port: 9000  
dependencies:
  services:  
    - service:  
        $ref: "#/components/services/apiOrderV3"  
        runOptions:  
          openapi:  
            type: mock  
            host: localhost  
            port: 9001  
components:  
  sources:  
    specmaticOrderContracts:  
      git:  
        url: https://github.com/specmatic/specmatic-order-contracts.git  
  services:  
    productSearchBffV4:  
      description: Product Search BFF v4 (provider)  
      definitions:  
        - definition:  
            source:  
              $ref: "#/components/sources/specmaticOrderContracts"  
            specs:  
              - io/specmatic/examples/store/openapi/product_search_bff_v4.yaml  
    apiOrderV3:  
      description: API Order V3 (consumer)  
      definitions:  
        - definition:  
            source:  
              $ref: "#/components/sources/specmaticOrderContracts"  
            specs:  
              - io/specmatic/examples/store/openapi/api_order_v3.yaml  
  examples:  
    commonExamples:  
      directories:  
        - order_service/examples  
        - product_service/examples  

```

--------------------------------

### Validate Multiple Specs with Default Example Locations

Source: https://docs.specmatic.io/features/external_examples

Use this command to validate examples when they are located alongside each specification file.

```bash
specmatic examples validate --specs-dir ./api-specs
```

--------------------------------

### Validate Examples with Docker

Source: https://docs.specmatic.io/features/external_examples

Use this Docker command to validate examples and detect competing requests for a given specification file.

```bash
docker run -v "$(pwd):/usr/src/app" specmatic/enterprise examples validate --spec-file "employee_details.yaml"
```

--------------------------------

### Basic `value: any` Matcher Example

Source: https://docs.specmatic.io/features/matchers

This example demonstrates the basic usage of `value: any` in a transient mock setup. It shows how the matcher can be used within an HTTP request body.

```json
{
  "transient": true,
  "http-request": {
    "method": "POST",
    "path": "/echo",
    "body": {
      "text": "$match(dataType: string, value: any, times: 2)"
    }
  },
  "http-response": {
    "status": 200,
    "body": {
      "echoedText": "$(text)"
    }
  }
}
```

--------------------------------

### Example of a Failing Contract Test with WIP

Source: https://docs.specmatic.io/contract_driven_development/contract_testing

This example demonstrates how to include a failing contract test case in the contract without breaking the build. The example name must start with '[WIP]'. This is useful for tracking contract violations that may take time to fix.

```yaml
[WIP] SUCCESS:  
  value:  
    id: 10  
    name: "Herbie"  
```

--------------------------------

### Start Specmatic Stub Server (NPM)

Source: https://docs.specmatic.io/features/json_schema/discriminator

Starts the Specmatic stub server using npx. Ensure the petstore.yaml is accessible.

```bash
npx specmatic mock petstore.yaml  
```

--------------------------------

### Search John Example (phonebook_examples/search_john.json)

Source: https://docs.specmatic.io/contract_driven_development/service_virtualization

An example for the /search endpoint that uses a 'bodyRegex' to match incoming request bodies starting with 'John' (case-insensitive). This enables flexible matching for plain text requests.

```json
{
  "http-request": {
    "path": "/search",
    "method": "POST",
    "headers": {
      "Content-Type": "text/plain"
    },
    "body": "(string)",
    "bodyRegex": "^[Jj][Oo][Hh][Nn].*$"
  },
  "http-response": {
    "status": 200,
    "body": [
      {
        "name": "John Doe",
        "number": "123-456-7890"
      },
      {
        "name": "John Smith",
        "number": "987-654-3210"
      },
      {
        "name": "John Johnson",
        "number": "555-555-5555"
      }
    ],
    "headers": {
      "Content-Type": "application/json"
    },
    "status-text": "OK"
  }
}

```

--------------------------------

### Start Specmatic Stub Server (Docker)

Source: https://docs.specmatic.io/features/json_schema/discriminator

Starts the Specmatic stub server using Docker, mounting the petstore.yaml file. Ensure the local directory is correctly mapped.

```bash
docker run -v "/local-directory/petstore.yaml:/usr/src/app/petstore.yaml" -p 9000:9000 specmatic/specmatic mock "petstore.yaml"  
```

--------------------------------

### Complete Sample Configuration

Source: https://docs.specmatic.io/references/configuration/complete-examples

This JSON configuration file outlines a full Specmatic setup, including service definitions, dependencies, component configurations for sources, services, run options, and adapters, as well as detailed Specmatic settings for backward compatibility, governance, and licensing.

```json
{
  "version": 3,
  "systemUnderTest": {
    "service": {
      "$ref": "#/components/services/onlineStoreServiceV1",
      "runOptions": {
        "$ref": "#/components/runOptions/onlineStoreServiceV1Test"
      }
    }
  },
  "dependencies": {
    "services": [
      {
        "service": {
          "$ref": "#/components/services/orderServiceV1",
          "runOptions": {
            "$ref": "#/components/runOptions/orderServiceV1Mock"
          }
        }
      }
    ]
  },
  "components": {
    "sources": {
      "centralContractRepo": {
        "git": {
          "url": "https://github.com/specmatic/specmatic-order-contracts.git"
        }
      }
    },
    "services": {
      "onlineStoreServiceV1": {
        "description": "Online Store Service (V1)",
        "definitions": [
          {
            "definition": {
              "source": {
                "$ref": "#/components/sources/centralContractRepo"
              },
              "specs": [
                "io/specmatic/examples/store/openapi/online_store_v1.yaml"
              ]
            }
          }
        ]
      },
      "orderServiceV1": {
        "description": "Payment Service (V1)",
        "definitions": [
          {
            "definition": {
              "source": {
                "$ref": "#/components/sources/centralContractRepo"
              },
              "specs": [
                "io/specmatic/examples/store/openapi/api_order_v1.yaml"
              ]
            }
          }
        ]
      }
    },
    "runOptions": {
      "onlineStoreServiceV1Test": {
        "openapi": {
          "type": "test",
          "baseUrl": "http://localhost:8080"
        }
      },
      "orderServiceV1Mock": {
        "openapi": {
          "type": "mock",
          "baseUrl": "http://localhost:8090"
        }
      }
    },
    "adapters": {
      "stub-hoks": {
        "test_load_contract": "python test_load_contract.py",
        "stub_load_contract": "python stub_load_contract.py",
        "post_specmatic_response_processor": "python post_specmatic_response_processor.py",
        "pre_specmatic_request_processor": "python pre_specmatic_request_processor.py",
        "pre_specmatic_response_processor": "python pre_specmatic_response_processor.py"
      }
    }
  },
  "specmatic": {
    "settings": {
      "backwardCompatibility": {
        "strictMode": true,
        "baseBranch": "origin/v3",
        "mock": {
          "delayInMilliseconds": 1000,
          "generative": true
        },
        "test": {
          "timeoutInMilliseconds": 1000
        }
      }
    },
    "governance": {
      "report": {
        "formats": [
          "ctrf",
          "html"
        ],
        "outputDirectory": "reports/specmatic"
      },
      "successCriteria": {
        "enforce": true,
        "maxMissedOperationsInSpec": 10,
        "minCoveragePercentage": 75
      }
    },
    "license": {
      "path": "{LICENSE_PATH:/path/to/license/file-or-directory}"
    }
  }
}
```

--------------------------------

### Execute a Command Inside the Specmatic Docker Container

Source: https://docs.specmatic.io/references/docker_images

After opening a shell, you can execute Specmatic commands directly within the container. This example shows how to get help.

```docker
specmatic --help
```

--------------------------------

### OpenAPI Schema with Invalid Discriminator Setup

Source: https://docs.specmatic.io/rules

This example shows an OpenAPI schema where the discriminator property is declared but not defined in the subschemas. Validation fails because the correct schema cannot be determined.

```yaml
oneOf:
  - $ref: "#/components/schemas/Cat"
  - $ref: "#/components/schemas/Dog"
discriminator:
  propertyName: type
  mapping:
    Cat: "#/components/schemas/Cat"
    Dog: "#/components/schemas/Dog"
components:
  schemas:
    Cat:
      type: object
      required:
        - whiskers
      properties:
        whiskers:
          type: integer
    Dog:
      type: object
      required:
        - bark
      properties:
        bark:
          type: boolean

```

--------------------------------

### Start Async Messaging Mock Server

Source: https://docs.specmatic.io/supported_protocols/asyncapi

Start a mock/stub server for async messaging protocols like Kafka. Supports external brokers or an in-memory Kafka broker. Use 'stub' or 'virtualize' as aliases.

```bash
specmatic-enterprise virtualize [OPTIONS]
```

--------------------------------

### Complete Specmatic Configuration Example (YAML v3)

Source: https://docs.specmatic.io/references/configuration/getting-started

This example demonstrates a full Specmatic configuration for testing a Pet Store service while mocking a Payment service. It includes system under test, dependencies, data sources, service definitions, and run options.

```yaml
version: 3  


systemUnderTest:  
  service:  
    $ref: "#/components/services/petStoreService"  
  runOptions:  
    $ref: "#/components/runOptions/petStoreTest"  
  data:  
    examples:  
      - directories:  
          - ./src/test/resources/petstore  
  
dependencies:
  services:  
    - service:  
        $ref: "#/components/services/paymentService"  
      runOptions:  
        $ref: "#/components/runOptions/paymentMock"  
      data:  
        examples:  
          - directories:  
              - ./src/test/resources/payment  
  
specmatic:
  governance:  
    successCriteria:  
      minCoveragePercentage: 0  
      maxMissedOperationsInSpec: 0  
      enforce: true  
  settings:  
    test:  
      schemaResiliencyTests: all  
  
components:
  sources:  
    specmaticOrderContracts:  
      git:  
        url: https://github.com/specmatic/specmatic-order-contracts.git  
  
  services:  

    petStoreService:  
      description: Pet Store Service  
      definitions:  
        - definition:  
            source:  
              $ref: "#/components/sources/specmaticOrderContracts"  
            specs:  
              - com/petstore/store.yaml  
  
    paymentService:  
      description: Payment Service  
      definitions:  
        - definition:  
            source:  
              $ref: "#/components/sources/specmaticOrderContracts"  
            specs:  
              - com/petstore/payment.yaml  
  
  runOptions:  

    petStoreTest:  
      openapi:  
        type: test  
        baseUrl: "{PETSTORE_URL:http://localhost:8080}"  
        filter: "PATH!='/health,/swagger'"  
        actuatorUrl: "{PETSTORE_URL:http://localhost:8080}/actuator/mappings"  
  
    paymentMock:  
      openapi:  
        type: mock  
        baseUrl: "http://localhost:8090"  

```

--------------------------------

### HTTP Method Mismatch Example

Source: https://docs.specmatic.io/rules

Illustrates a scenario where the HTTP method in a request (POST) does not match the method defined in the API specification (GET). This rule helps identify incorrect operation calls.

```yaml
paths:
  /orders:
    get:
      responses:
        "200":
          description: OK
```

```http
POST /orders HTTP/1.1
```

--------------------------------

### Start Specmatic GraphQL Stub Server

Source: https://docs.specmatic.io/supported_protocols/graphql

Run this Docker command to start a mock server based on your GraphQL SDL file. It mounts the current directory to /sandbox and uses the enterprise version of Specmatic.

```bash
docker run --network host -v "$(pwd):/sandbox" specmatic/enterprise mock /sandbox/product-api.graphql
```

--------------------------------

### Run Mock Server and Verify API

Source: https://docs.specmatic.io/getting_started/studio_quick_start

Starts a mock server based on petstore.yaml and verifies API access using curl.

```bash
curl https://studio.specmatic.io:<port number>/pets/123
```

--------------------------------

### Spin up a mock server on a custom port using npx

Source: https://docs.specmatic.io/getting_started/cli_quick_start

Use npx to run Specmatic and start a mock server on a custom port (9002). This is a convenient way to manage Specmatic without global installation.

```bash
npx specmatic mock service.yaml --port 9002
```

--------------------------------

### Verifying Side Effects with an After HTTP Request

Source: https://docs.specmatic.io/features/testing_event_flows-and_behaviors

This example file verifies that after receiving an 'OutForDelivery' event, the order status is updated to 'SHIPPED'. It uses an 'after' fixture to make an HTTP GET request and check the response body.

```json
{
  "id": "order-out-for-delivery",
  "name": "ORDER_OUT_FOR_DELIVERY",
  "receive": {
    "topic": "out-for-delivery-orders",
    "payload": {
      "orderId": 456,
      "deliveryAddress": "1234 Elm Street, Springfield",
      "deliveryDate": "2025-04-14"
    }
  },
  "after": [
    {
      "type": "http",
      "http-request": {
        "baseUrl": "http://localhost:8080",
        "path": "/orders/456?status=SHIPPED",
        "method": "GET"
      },
      "http-response": {
        "status": 200,
        "body": {
          "id": "$match(exact: 456)",
          "status": "SHIPPED"
        }
      },
      "timeout": "PT10S"
    }
  ]
}

```

--------------------------------

### Template Syntax Example

Source: https://docs.specmatic.io/references/configuration/template-values

Illustrates the basic template syntax for environment variables with a default value.

```text
{ENV_VAR_NAME:defaultValue}
```

--------------------------------

### Generate Dictionary with Examples Directory

Source: https://docs.specmatic.io/features/dictionary

Use this Docker command to generate a dictionary file by specifying the OpenAPI spec file and the directory containing examples.

```bash
docker run --rm -v "$(pwd):/usr/src/app" specmatic/enterprise examples dictionary --spec-file employees.yaml --examples-dir ./examples
```

--------------------------------

### Specific Workflow API Selector Configuration

Source: https://docs.specmatic.io/features/workflow/workflow-within-a-specification

Configure workflow to use a specific API selector for using an ID, rather than a wildcard. This example extracts an ID from a POST response and uses it specifically for GET requests to retrieve order details.

```yaml
workflow:
  ids:
    # Get the id from the test for the POST operation on /orders that expects a 201
    "POST /orders -> 201":
      extract: "BODY.id" # extract the id from this path in the response payload
    # Use the id in other APIs where the `use` clause finds something
    "GET /orders/(orderId:string) -> 200":
      use: "PATH.orderId" # use the id as the path parameter the request for tests that fetch the details for an order

```

--------------------------------

### OpenAPI Global and Operation-Level Security Example

Source: https://docs.specmatic.io/features/authentication

This OpenAPI 3.0.1 snippet demonstrates how to define a global default authentication scheme (BearerAuth) and override it for a specific operation (GET /products) with a different scheme (basicAuth). Use this to configure authentication requirements for your API endpoints.

```yaml
openapi: 3.0.1  

security:  
  - BearerAuth: []   # Global default  
  
paths:  
  /products:  
    get:  
      security:  
        - basicAuth: []   # Overrides global for GET /products  
      responses:  
        "200":  
          description: OK  

```

--------------------------------

### Using Specmatic License with Docker (Help)

Source: https://docs.specmatic.io/enterprise_onboarding/license_key

View Specmatic help information when using Docker on Linux/macOS, demonstrating how the license volume is mounted.

```bash
docker run -it --rm -v ~/.specmatic:/root/.specmatic specmatic/enterprise -h
```

--------------------------------

### Install Specmatic Redis via PowerShell Script

Source: https://docs.specmatic.io/download

Installs the latest version of Specmatic Redis using a PowerShell command to download and execute an installation script. Ensure Java 17 or above is installed.

```powershell
irm https://docs.specmatic.io/install-specmatic-redis.ps1 | iex  
```

--------------------------------

### Install Specmatic Redis via Shell Script

Source: https://docs.specmatic.io/download

Installs the latest version of Specmatic Redis using a curl command to download and execute an installation script. Ensure Java 17 or above is installed.

```bash
curl https://docs.specmatic.io/install-specmatic-redis.sh | bash  
```

--------------------------------

### Install Specmatic using pip (latest)

Source: https://docs.specmatic.io/download

Install the latest version of Specmatic using pip, the Python package installer.

```bash
pip install specmatic  

```

--------------------------------

### Specmatic v3 Configuration Example

Source: https://docs.specmatic.io/references/configuration/migrating-config-v2-to-v3

Demonstrates the v3 configuration format with explicit wiring for System Under Test (SUT) and dependencies, including service definitions and run options.

```yaml
version: 3

systemUnderTest:
  service:
    $ref: "#/components/services/petStoreService"
  runOptions:
    $ref: "#/components/runOptions/petStoreTest"
  
dependencies:
  services:
    - service:
        $ref: "#/components/services/paymentService"
      runOptions:
        $ref: "#/components/runOptions/paymentMock"
  
components:
  sources:
    centralContracts:
      git:
        url: https://github.com/specmatic/specmatic-order-contracts.git
  services:
    petStoreService:
      definitions:
        - definition:
            source:
              $ref: "#/components/sources/centralContracts"
            specs:
              - com/petstore/store.yaml
    paymentService:
      definitions:
        - definition:
            source:
              $ref: "#/components/sources/centralContracts"
            specs:
              - com/petstore/payment.yaml
  runOptions:
    petStoreTest:
      openapi:
        type: test
        baseUrl: http://localhost:8080
    paymentMock:
      openapi:
        type: mock
        baseUrl: http://localhost:8090

```

--------------------------------

### Start Specmatic Stub Server (Java)

Source: https://docs.specmatic.io/features/json_schema/discriminator

Starts the Specmatic stub server using a JAR file. Ensure the petstore.yaml is accessible.

```java
java -jar specmatic.jar mock petstore.yaml  
```

--------------------------------

### GraphQL Stub Response with Example Data

Source: https://docs.specmatic.io/supported_protocols/graphql

Example of a response received from the stub server when using custom example data.

```json
{
 "data": {
   "findAvailableProducts": [
     {
       "id": "10",
       "name": "The Almanac",
       "inventory": 10,
       "type": "book"
     },
     {
       "id": "20",
       "name": "iPhone",
       "inventory": 15,
       "type": "gadget"
     }
   ]
 }
}
```

--------------------------------

### Validate Test Examples

Source: https://docs.specmatic.io/supported_protocols/asyncapi

Validate test examples against an AsyncAPI specification. Requires the path to the specification file and optionally accepts a path to an examples directory.

```bash
specmatic-enterprise examples validate [OPTIONS]
```

--------------------------------

### Install Specmatic Enterprise via Shell Script

Source: https://docs.specmatic.io/download

Download and execute the Specmatic Enterprise installation script using curl. This command installs the latest version of the tool.

```bash
curl https://docs.specmatic.io/install-specmatic-enterprise.sh | bash  
```

--------------------------------

### Spin up a mock server with Docker (Windows Command Prompt)

Source: https://docs.specmatic.io/getting_started/cli_quick_start

This command is the Windows equivalent for starting a Specmatic mock server with Docker. It ensures your local OpenAPI specification is accessible to the mock server.

```bash
docker run -v "%cd%:/specs" -p 9000:9000 specmatic/specmatic mock "/specs/service.yaml"
```

--------------------------------

### Install Specmatic Enterprise via PowerShell Script

Source: https://docs.specmatic.io/download

Download and execute the Specmatic Enterprise installation script using PowerShell's Invoke-WebRequest and Invoke-Expression. This command installs the latest version.

```powershell
irm https://docs.specmatic.io/install-specmatic-enterprise.ps1 | iex  
```

--------------------------------

### Configure Custom Example Directories in specmatic.yaml

Source: https://docs.specmatic.io/supported_protocols/graphql

Specifies custom directories for example data within the specmatic.yaml configuration file for services.

```yaml
version: 3
dependencies:
  services:
    - service:
        $ref: "#/components/services/yourService"
        runOptions:
          $ref: "#/components/runOptions/yourServiceMock"
        data:
          examples:
            - directories:
                - ./custom-examples
                - ./more-examples
components:
  sources:
    yourContracts:
      git:
        url: https://your-central-contract-repo.com
        branch: main
  services:
    yourService:
      description: Your GraphQL Service
      definitions:
        - definition:
            source:
              $ref: "#/components/sources/yourContracts"
            specs:
              - spec:
                  id: yourServiceSpec
                  path: /path/to/your/service.graphqls
  runOptions:
    yourServiceMock:
      graphqlsdl:
        type: mock
        specs:
          - spec:
              id: yourServiceSpec
              host: localhost
              port: 9000
```

--------------------------------

### Manually Create an Example File

Source: https://docs.specmatic.io/features/external_examples

Create an example JSON file for Specmatic when the commercial version is not available. This file defines the HTTP request and expected HTTP response for testing.

```json
{
    "http-request": {
        "method": "PATCH",
        "path": "/employees",
        "body": {
            "employeeCode": "pqrxyz",
            "name": "Jamie",
            "department": "IT",
            "designation": "Manager"
        }
    },
    "http-response": {
        "status": 200,
        "body": {
            "id": 10,
            "employeeCode": "pqrxyz",
            "name": "Jamie",
            "department": "(string)",
            "designation": "(string)"
        }
    }
}
```

--------------------------------

### Modify Example Status Value to Boolean

Source: https://docs.specmatic.io/getting_started/studio_quick_start

Update the 'status' field in an example response to match the new 'boolean' type defined in the OpenAPI specification. This ensures examples align with the contract.

```yaml
  examples:
    SCOOBY_200_OK:
      value:
        id: 1
        name: Scooby
        type: Golden Retriever
        status: true # change the value from "Adopted" to true
```

--------------------------------

### Start Stub Server with npm

Source: https://docs.specmatic.io/features/external_examples

Command to start the Specmatic stub server using npx, referencing a contract file for mock data generation.

```bash
npx specmatic mock employee_details.yaml
```

--------------------------------

### Install Specific Version of Specmatic Redis via Shell Script

Source: https://docs.specmatic.io/download

Installs a specific version of Specmatic Redis by passing the version number to the installation script. Replace VERSION with the desired version.

```bash
curl https://docs.specmatic.io/install-specmatic-redis.sh | bash -- --version VERSION  
```

--------------------------------

### Start Specmatic Mock Server

Source: https://docs.specmatic.io/supported_protocols/asyncapi

This Docker command starts a Specmatic mock server using the enterprise image, mounting the current directory for configuration and contract access.

```bash
docker run --rm --network host -v "$(pwd):/usr/src/app" specmatic/enterprise mock  

```

--------------------------------

### Externalized Example Data for gRPC Method (Error)

Source: https://docs.specmatic.io/supported_protocols/grpc

JSON format for simulating error scenarios with externalized example data for a gRPC method. This example includes an errorCode and errorMessage for the createOrder method.

```json
{
  "fullMethodName": "com.store.order.bff.OrderService/createOrder",
  "request": {
    "productId": 50000,
    "count": 8
  },
  "response": {
    "errorCode": 5,
    "errorMessage": "Product with ID 50000 was not found"
  }
}
```

--------------------------------

### Specmatic Mock Help for HTTPS Options

Source: https://docs.specmatic.io/contract_driven_development/service_virtualization

View the help command for Specmatic Mock to understand the available options for configuring HTTPS, including key store file, passwords, and key passwords.

```bash
% specmatic mock --help  

...  

      --httpsKeyStore=<keyStoreFile>  

                             Run the proxy on https using a key in this store  

      --httpsKeyStorePassword=<keyStorePassword>  

                             Run the proxy on https, password for pre-existing  

                               key store  

      --httpsPassword=<keyPassword>  

                             Key password if any  



```

--------------------------------

### Install Specmatic NPM Package

Source: https://docs.specmatic.io/getting_started/cli_quick_start

Installs the Specmatic npm package globally on your system.

```bash
npm install -g specmatic  
```

--------------------------------

### Start Service with Docker Compose

Source: https://docs.specmatic.io/contract_driven_development/contract_repositories/central_contract_repository

Start the service using Docker Compose. This command should be run from the relevant service repository.

```bash
docker compose up --build
```

--------------------------------

### Using Specmatic License with Docker (Help - Command Prompt)

Source: https://docs.specmatic.io/enterprise_onboarding/license_key

View Specmatic help information when using Docker on Windows with Command Prompt, illustrating the license volume mount.

```cmd
docker run -it --rm -v "%USERPROFILE%\.specmatic:/root/.specmatic" specmatic/enterprise -h
```

--------------------------------

### Install Specific Version Specmatic Enterprise via Shell Script

Source: https://docs.specmatic.io/download

Install a specific version of Specmatic Enterprise by providing the version number as an argument to the installation script. Replace VERSION with the desired tag.

```bash
curl https://docs.specmatic.io/install-specmatic-enterprise.sh | bash -- --version VERSION  
```

--------------------------------

### Verify by Example ID with cURL

Source: https://docs.specmatic.io/supported_protocols/asyncapi/kafka

Verify message counts based on example IDs. Provide a comma-separated list of example IDs to check their corresponding message counts received since the last snapshot.

```bash
curl "http://localhost:9999/_specmatic/verify?exampleIds=success-case,invalid-order"
```

--------------------------------

### Spin up a mock server with Docker (macOS/Linux/PowerShell)

Source: https://docs.specmatic.io/getting_started/cli_quick_start

Use this command to start a Specmatic mock server using Docker. It maps the local specs directory to the container and exposes the mock server on port 9000.

```bash
docker run -v "$(pwd):/specs" -p 9000:9000 specmatic/specmatic mock "/specs/service.yaml"
```

--------------------------------

### Example JSON for Competing Requests (HTTP 400)

Source: https://docs.specmatic.io/features/external_examples

This JSON defines an example request and its corresponding HTTP 400 response. It is used to demonstrate competing requests when multiple examples have the same request but different responses.

```json
{
"http-request": {
  "method": "PATCH",
  "path": "/employees",
  "body": {
    "name": "Jamie",
    "department": "Backend",
    "designation": "Engineer"
  }
},
"http-response": {
  "status": 400,
  "body": {
    "message": "Invalid value"
  }
}
}
```

--------------------------------

### Start Specmatic gRPC Mock Service with Docker

Source: https://docs.specmatic.io/supported_protocols/grpc

Use this command to start the Specmatic gRPC stub/service virtualization service. It mounts the current directory to access `specmatic.yaml` for configuration.

```bash
docker run --network host -v "$(pwd):/usr/src/app" specmatic/enterprise mock
```

--------------------------------

### Start Stub Server with Java

Source: https://docs.specmatic.io/features/external_examples

Command to start the Specmatic stub server using a JAR file, referencing a contract file for mock data generation.

```java
java -jar specmatic.jar mock employee_details.yaml
```

--------------------------------

### Example JSON for Competing Requests (HTTP 200)

Source: https://docs.specmatic.io/features/external_examples

This JSON defines an example request and its corresponding HTTP 200 response. It is used to demonstrate competing requests when multiple examples have the same request but different responses.

```json
{
"http-request": {
  "method": "PATCH",
  "path": "/employees",
  "body": {
    "name": "Jamie",
    "department": "Backend",
    "designation": "Engineer"
  }
},
"http-response": {
  "status": 200,
  "body": {
    "id": 10,
    "employeeCode": "pqrxyz",
    "name": "Jamie",
    "department": "Backend",
    "designation": "Engineer"
  }
}
}
```

--------------------------------

### Query All Fields with GraphQL

Source: https://docs.specmatic.io/supported_protocols/graphql

Example cURL command to query all fields defined in the GraphQL example.

```bash
curl -X POST http://localhost:9000/graphql \
  -H "Content-Type: application/json" \
  -d '{ \
    "query": "query { findAvailableProducts(type: gadget, pageSize: 10) { id name inventory type } }" \
  }'
```