Optic

Run locally

Prevent breaking changes using optic diff

Optic can detect breaking changes between any two versions of an OpenAPI specification. Optic can lookup the versions using Git tags and branch names so you don’t need to copy files around.

Compares the HEAD to the main branch

optic diff openapi.yml --base main --check

Compares two branches by name

optic diff feature/example:openapi.yml develop:main --check

Compare files in against a remote URL

optic diff --check \
https://raw.githubusercontent.com/opticdev/bookstore-example/89c9a67935c850c1051059f4c719ef433dea8cc0/openapi.yml \
https://raw.githubusercontent.com/opticdev/bookstore-example/ac5f3c55a6f7f27c482a557563686d0328dafb55/openapi.yml

Read Documentation

Test the accuracy of your documentation using optic capture

It can be difficult to keep an OpenAPI in-sync with your implementation. Optic tests if your OpenAPI is accurate by capturing traffic from your tests and comparing it to the spec.

Think of it like Snapshot testing, but for your API’s behavior, with OpenAPI as the snapshot.

Try it out with our example repo

You can clone our example repo to try out `optic capture` against a repo that is already set up. ```bash git clone git@github.com:opticdev/examples.git cd ./examples/apps/bookstore-api npm install ``` Once you've set up the repo, you can run `optic capture openapi.yml` to verify traffic against your OpenAPI spec, and `optic capture openapi.yml --update=interactive` to update any diffs.

To start capturing your test traffic, run:

optic capture init openapi.yml

Configuration will be generated for you in the optic.yml file

capture:
  openapi.yml:
    server:
      command: npm start # your server start command
      url: http://localhost:8080 # where your server starts
    requests:
      send:
        - path: /
          method: GET
        - path: /users/create
          method: POST
          headers:
            content-type: application/json;charset=UTF-8
          data:
            name: Hank

Then you can run:

optic capture openapi.yml

When Optic detects a diff, you can correct it manually, or run optic capture --update=interactive to have Optic figures out exactly which lines of OpenAPI need to be updated and make the changes for you.

optic capture openapi.yml --update=interactive

Read Documentation

Start running in CI

To start using Optic in CI, follow this guide. We provide template workflows for GitHub and GitLab to help you run Optic as a CI check:

Github

# .github/workflows/optic.yml
name: optic
on:
  pull_request:
  push:
    branches:
      - "main"

jobs:
  run:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v3

      - name: Install Optic
        run: npm install --location global @useoptic/optic

      - name: Run Optic
        env:
          OPTIC_TOKEN: ${{ secrets.OPTIC_TOKEN }}
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: optic run

Gitlab

Don’t forget to add the OPTIC_TOKEN and OPTIC_GITLAB_TOKEN variables to your workflow.

# .gitlab-ci.yml
optic-default-branch-push:
  image: node:latest
  rules:
    - if: $CI_PIPELINE_SOURCE == "push" && OPTIC_TOKEN && $CI_COMMIT_REF_NAME == $CI_DEFAULT_BRANCH
  script:
    - npm install -g @useoptic/optic
    - optic run

optic-merge-request:
  image: node:latest
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event" && $OPTIC_TOKEN
  script:
    - npm install -g @useoptic/optic
    - export OPTIC_RESULT=0; optic run || export OPTIC_RESULT=$?
    - if [ $OPTIC_RESULT -ne 0 ]; then exit 1; fi;

Resources

• Read our full documentation here
• Need help? Book office hours
• Join us on Discord