Skip to main content

Contract Management

Versions 3 - systemUnderTest and dependencies​

In v3, we define services under components.services and the specifications implemented by the service are defined within the service definition. We define a 'systemUnderTest' which references the service being tested and its run options. We can also define the dependencies of the service under 'dependencies.services' along with their run options.

Versions 2 - Provides and Consumes​

In v2, a service needs to list the API Specifications it implements under the provides attribute and the API Specifications of its dependencies under the consumes attribute.

Contracts from Git Repository​

Configure Specmatic to pull contracts from a Git repository:

specmatic.yaml
version: 3
systemUnderTest:
  service:
    $ref: "#/components/services/onlineStoreServiceV1"
    runOptions:
      $ref: "#/components/runOptions/onlineStoreServiceV1"
dependencies:
  services:
    - service:
        $ref: "#/components/services/orderServiceV1"
        runOptions:
          $ref: "#/components/runOptions/orderServiceV1"
components:
  sources:
    specmaticOrderContracts:
      git:
        url: https://github.com/specmatic/specmatic-order-contracts.git
  services:
    onlineStoreServiceV1:
      description: Online Store Service (V1)
      definitions:
        - definition:
            source:
              $ref: "#/components/sources/specmaticOrderContracts"
            specs:
              - io/specmatic/examples/store/openapi/online_store_v1.yaml
    orderServiceV1:
      description: Payment Service (V1)
      definitions:
        - definition:
            source:
              $ref: "#/components/sources/specmaticOrderContracts"
            specs:
              - io/specmatic/examples/store/openapi/api_order_v1.yaml
  runOptions:
    onlineStoreServiceV1:
      openapi:
        type: test
        baseUrl: http://localhost:8080
    orderServiceV1:
      openapi:
        type: mock
        baseUrl: http://localhost:8090

Contracts from Local Filesystem​

If you just need to use specifications from your local file system, specify filesystem field within contracts (if not specified, directory will default to current directory):

specmatic.yaml
version: 3
systemUnderTest:
  service:
    $ref: "#/components/services/onlineStoreServiceV1"
    runOptions:
      $ref: "#/components/runOptions/onlineStoreServiceV1"
dependencies:
  services:
    - service:
        $ref: "#/components/services/orderServiceV1"
        runOptions:
          $ref: "#/components/runOptions/orderServiceV1"
components:
  sources:
    specmaticOrderContracts:
      filesystem:
        directory: path/to/spec/directory
  services:
    onlineStoreServiceV1:
      description: Online Store Service (V1)
      definitions:
        - definition:
            source:
              $ref: "#/components/sources/specmaticOrderContracts"
            specs:
              - io/specmatic/examples/store/openapi/online_store_v1.yaml
    orderServiceV1:
      description: Payment Service (V1)
      definitions:
        - definition:
            source:
              $ref: "#/components/sources/specmaticOrderContracts"
            specs:
              - io/specmatic/examples/store/openapi/api_order_v1.yaml
  runOptions:
    onlineStoreServiceV1:
      openapi:
        type: test
        baseUrl: http://localhost:8080
    orderServiceV1:
      openapi:
        type: mock
        baseUrl: http://localhost:8090

Note that the specification paths are relative paths. This means that they must be in the same directory as the current directory.

You can also provide absolute paths in case they are somewhere else on the filesystem.