Insights Set Up Guide

Overview

This guide explains how to integrate Specmatic Insights into your API ecosystem. It covers CI/CD report publishing, configuration, visualization, proxy settings, and troubleshooting for teams using Spec-Driven API Development.

Prerequisites

Note: To publish builds to Specmatic Insights, you must have a valid license key issued by Specmatic. Please ensure you have obtained your license before proceeding with the setup.

For details on acquiring and managing your license, refer to the License Key Guide.

Step 1: Setting up CI/CD Pipelines with Specmatic

Please go through the detailed Continuous Integration guide to set up Specmatic in your CI/CD pipelines for:

• Central Contract Repo
• API Consumers
• API Providers

Step 2: Configuring Specmatic Insights

Integrating with CI/CD Pipelines

Please add the following 2 steps to your CI/CD pipeline configuration:

note

Legacy build reporter support has been removed. If your pipeline still uses specmatic-insights-build-reporter-github-action or specmatic-insights-github-build-reporter, migrate to direct reporting from specmatic test, specmatic mock, or specmatic run-suite using the Migration Guide.

GitHub

- name: Write specmatic license key to file
  run: |
    mkdir -p ~/.specmatic
    echo "${{ secrets.SPECMATIC_LICENSE_KEY }}" > ~/.specmatic/specmatic-license.txt

- name: Run contract tests and publish to Specmatic Insights
  if: github.ref == 'refs/heads/main'
  run: |
    docker run --rm \
      -v ~/.specmatic:/root/.specmatic \
      -v ${{ github.workspace }}:/usr/src/app \
      specmatic/enterprise \
      test \
      --ci \
      --build-id ${{ github.run_id }} \
      --branch-name ${{ github.ref_name }} \
      --repo-name ${{ github.event.repository.name }} \
      --repo-id ${{ github.repository_id }} \
      --repo-url ${{ github.event.repository.html_url }}

GitLab

publish_specmatic_insights:
  stage: report
  image:
    name: specmatic/specmatic:latest
    entrypoint: [""]

  rules:
    - if: '$CI_COMMIT_BRANCH == "main"'
      when: on_success
    - when: never

  before_script:
    - mkdir -p ~/.specmatic
    - echo "$SPECMATIC_LICENSE_KEY" > ~/.specmatic/specmatic-license.txt

  script:
    - |
      specmatic test \
        --ci \
        --build-id "$CI_PIPELINE_ID" \
        --branch-name "$CI_COMMIT_BRANCH" \
        --repo-name "$CI_PROJECT_NAME" \
        --repo-id "$CI_PROJECT_ID" \
        --repo-url "$CI_PROJECT_URL"

This will ensure that only when you merge the changes to your main branch, your build reports are sent to Specmatic Insights after each CI/CD pipeline execution, allowing Specmatic Insights to aggregate and visualize your API ecosystem effectively.

Step 3: Visualizing Your API Ecosystem

Viewing Your Service Mesh

Once your CI/CD pipelines are set up and executed, you should be able to view your service mesh on the Specmatic Insights dashboard:

1. Log in to your Specmatic Insights account.
2. After successful login, you will automatically land on the main dashboard.
3. Now, you should see a visualization of your services and their dependencies.

Next Steps

Congratulations! You've set up a powerful system for managing and visualizing your APIs. Here are some next steps to consider:

• Integrate more of your services into this ecosystem.
• Use the insights gained to identify areas for improvement in your API design and usage.
• Leverage Specmatic for contract-driven API development.

Working with proxies

For outbound proxy configuration used by Insights publishing and other Specmatic requests, see Network Proxy Settings.

Troubleshooting

Tip: If you encounter issues, check the following common problems:

• License Key Invalid or Missing: Ensure your license key is correctly configured and not expired. Refer to the License Key Guide.
• Build Report Not Visible: Confirm that your CI pipeline is publishing reports to the correct Insights endpoint and that network access is not blocked.
• Specmatic Docker Image Issues: Make sure you are using the latest Specmatic Docker image and that your environment has Docker installed and running.
• API Spec Errors: Validate your OpenAPI specifications for syntax and compatibility before running the pipeline.
• Dashboard Not Showing Services:
  1. Ensure your CI/CD pipelines are correctly set up with the Specmatic Insights Build Reporter.
  2. Verify that your Specmatic reports are being generated in the specified directory (e.g., ./build/reports/specmatic).

For additional help, consult the Specmatic documentation or contact Specmatic support.