Aidan Cunniffe acunniffe

At Optic we work with a lot of different kinds of diffs. We call a diff between traffic and a spec, a "diff" and a diff between two versions of an OpenAPI document a "changelog"

Optic CI rules take advantage of this pipeline, which, also can support producing changelogs between any two OpenAPI files

reads your disk / git repo to get the full spec, with all refs resolved
compute facts about the API specification that are true, independent of formatting, ordering, etc. Notice how if you change the order of Operations in optic-ci there's no changelog, even though there's a git diff. This is essential to making a real changelog, that works across a variety of use cases
facts are then compared to produce changes
Optic CI Rules look for changes they care about and execute to give you results

If you stop at step 3, you have a changelog between the two files.

import { Callout } from "nextra-theme-docs";

Capturing Traffic

Optic Capture helps create OpenAPI specifications and keep them up to date by examining the traffic to your API. Under the hood the following happens when running Capture,

Your API is started via a command you provide.
A reverse proxy is configured to send traffic to your API.
A command or set of requests you provide is run, generating traffic to the proxy.
Optic observes the traffic as it passes through the proxy.

	[{
	"url": "https://api.stripe.com/v1/balance_transactions",
	"method": "GET",
	"request": {
	"headers_shape_hash": "286b9d7d500fd5de10ce6614a011a8ec0ea38102",
	"body": {
	"content-type": "application/json",
	"shape_hash": "421e6d804647dccef9e26bde65d120689ff2b28c"
	}
	},

	import {
	ConceptualLocation,
	IChange,
	IPathComponent,
	OpenApiFact,
	OpenApiKind,
	OpenApiOperationFact,
	OpenApiRequestParameterFact,
	} from '../types';
	import equals from 'lodash.isequal';