OpenAPI Spec Diff Auditor

Store Positioning

Store title: OpenAPI Spec Diff Auditor

Short description: Diff OpenAPI specs for breaking changes, added or removed endpoints, required parameters, response drift, and schema compatibility. by default.

SEO title: OpenAPI Spec Diff Auditor — API, schema, and developer QA

SEO description: Diff OpenAPI specs for breaking changes, added or removed endpoints, required parameters, response drift, and schema compatibility. by default. Use it to catch contract drift, schema mistakes, unsafe endpoint assumptions, and developer-tool quality issues before release.

Categories: SEO_TOOLS, DEVELOPER_TOOLS, AUTOMATION

Keywords: openapi, spec, diff, auditor, schema, change monitor, api testing, api/developer qa

Fixed-Inclusive PPE Pricing

This actor uses pay-per-event pricing. Event prices include Apify platform usage; users are not expected to pay a separate platform-usage pass-through charge for the configured pricing model.

• Tier: A1 — API/developer QA
• Primary event: schema-validated at $0.00650 base
• Default max charge: $10.00
• Store discounts: FREE/BRONZE base, SILVER discounted, GOLD deepest approved discount

Event set:

• actor-start: base $0.00500, GOLD $0.00400. Openapi Spec Diff Auditor: charged when actor start is completed. The price includes Apify platform usage; no separate usage pass-through is intended.
• schema-validated: base $0.00650, GOLD $0.00520. Openapi Spec Diff Auditor: charged when schema validated is completed. The price includes Apify platform usage; no separate usage pass-through is intended.
• contract-rule-checked: base $0.00390, GOLD $0.00312. Openapi Spec Diff Auditor: charged when contract rule checked is completed. The price includes Apify platform usage; no separate usage pass-through is intended.
• report-generated: base $0.05000, GOLD $0.04000. Openapi Spec Diff Auditor: charged when report generated is completed. The price includes Apify platform usage; no separate usage pass-through is intended.

Public Task Concepts

• Compare previous and current OpenAPI Spec Diff snapshots
• Monitor OpenAPI Spec Diff changes for a capped watchlist
• Build an OpenAPI Spec Diff change digest from supplied evidence
• Prioritize high-impact OpenAPI Spec Diff changes
• Export OpenAPI Spec Diff change rows for client review

What does OpenAPI Spec Diff Auditor do?

OpenAPI Spec Diff Auditor compares two OpenAPI specifications and returns structured compatibility findings for API teams, SDK maintainers, and integration owners. It is fixture-first and makes no network calls by default, so the default Apify quality run is deterministic, fast, and safe.

It detects:

• Added and removed endpoints by method and path
• Operation-level drift across summaries, parameters, request bodies, responses, and deprecation flags
• Newly required request parameters that can break existing clients
• Removed response codes and response schema fields
• Response field type changes and newly required response fields
• Invalid OpenAPI inputs before trusting diff output

Why Use This Actor

Capability	OpenAPI Spec Diff Auditor	Manual JSON diff	General API changelog monitor
OpenAPI-aware endpoint matching	Yes, by HTTP method and path	No	Usually partial
Breaking-change severity	Built in	No	Usually text-only
Fixture-first defaults	Yes	Depends on setup	Often network-first
Dataset rows for automation	Yes	No	Varies
KVS summary report	Yes	No	Varies
Cost per 1K audited targets	$9.80	Staff time	Varies

Use this actor when you need a clear compatibility signal, not a raw line-by-line diff. It is designed for release gates, SDK update reviews, partner API monitoring, and support delivery summaries.

How to Use

Start with the default input to see a tiny fixture diff:

{
  "sourceId": "example-billing-api",
  "includeReport": true,
  "allowUrlFetch": false,
  "maxTargets": 1,
  "maxChanges": 25
}

1. Paste the previous OpenAPI JSON or YAML text into previousSpec.
2. Paste the current OpenAPI JSON or YAML text into currentSpec.
3. Keep allowUrlFetch disabled unless you explicitly want capped URL fetching.
4. Run the actor and review dataset rows sorted by severity.
5. Open OPENAPI_DIFF_REPORT.md in the key-value store for a compact release summary.

Release Gate Review

Use one target with your last published spec and the release candidate spec. Set maxChanges high enough to capture all compatibility findings, then fail your downstream workflow if any critical row appears.

Multi-Spec Partner Audit

URL Fetch Opt-In

Set allowUrlFetch to true only when you want the actor to fetch previousSpecUrl and currentSpecUrl. Fetching is capped by timeout and byte size. Inline spec text remains the safest default.

Input Configuration

Field	Type	Default	Description
sourceId	string	example-billing-api	Stable label for a single top-level spec pair.
previousLabel	string	previous	Label for the older spec.
currentLabel	string	current	Label for the newer spec.
previousSpec	string	tiny fixture	Older OpenAPI JSON or simple YAML text.
currentSpec	string	tiny fixture	Newer OpenAPI JSON or simple YAML text.
previousSpecUrl	string	empty	Optional older spec URL, fetched only when enabled and spec text is blank.
currentSpecUrl	string	empty	Optional newer spec URL, fetched only when enabled and spec text is blank.
targets	array	[]	Optional list of spec pairs that overrides top-level fields.
maxTargets	integer	1	Maximum spec pairs audited per run.
maxChanges	integer	100	Maximum dataset rows emitted per target after severity sorting.
includeReport	boolean	true	Write JSON and Markdown report artifacts to the key-value store.
allowUrlFetch	boolean	false	Explicit opt-in for capped network fetches.
debug	boolean	false	Enable additional debug logs.

Output Format

Each dataset row is one compatibility finding:

{
  "changeId": "d9b77a3d18c67f21",
  "sourceId": "example-billing-api",
  "previousLabel": "previous",
  "currentLabel": "current",
  "status": "changed",
  "changeType": "removed",
  "category": "endpoint",
  "severity": "critical",
  "method": "GET",
  "path": "/v1/legacy-invoices",
  "identifier": "GET /v1/legacy-invoices",
  "previousValue": "operation fingerprint",
  "currentValue": null,
  "previousSpecUrl": null,
  "currentSpecUrl": null,
  "auditedAt": "2026-07-02T00:00:00.000Z",
  "recommendation": "Confirm GET /v1/legacy-invoices is intentionally removed and identify affected consumers before release."
}

Report artifacts:

• OPENAPI_DIFF_RESULTS.json: full structured result array
• OPENAPI_DIFF_SUMMARY.json: run counts, target summaries, and severity totals
• OPENAPI_DIFF_REPORT.md: concise Markdown report for release review

Integration Examples

Node.js

import { ApifyClient } from 'apify-client';

const client = new ApifyClient({ token: process.env.APIFY_TOKEN });
const run = await client.actor('junipr/openapi-spec-diff-auditor').call({
  previousSpec: JSON.stringify(previousOpenApi),
  currentSpec: JSON.stringify(currentOpenApi),
  maxChanges: 500
});

const { items } = await client.dataset(run.defaultDatasetId).listItems();
const critical = items.filter((item) => item.severity === 'critical');
if (critical.length) {
  throw new Error(`OpenAPI release has ${critical.length} critical compatibility changes`);
}

Python

from apify_client import ApifyClient

client = ApifyClient("APIFY_TOKEN")
run = client.actor("junipr/openapi-spec-diff-auditor").call(run_input={
    "previousSpec": previous_spec_text,
    "currentSpec": current_spec_text,
    "maxChanges": 500,
})

items = client.dataset(run["defaultDatasetId"]).list_items().items
critical = [item for item in items if item["severity"] == "critical"]
print(f"critical changes: {len(critical)}")

Tips and Advanced Usage

Performance Optimization

Keep specs inline for the most deterministic runs. Use maxTargets and maxChanges to bound work and output volume. The actor is designed for text parsing and does not need a browser, proxy, or external API.

URL Fetch Safety

Network access is disabled by default. If enabled, the actor uses a timeout and byte cap for each spec URL. Prefer pinned spec artifacts over mutable documentation URLs when using this in CI.

Interpreting Severity

critical means a change is likely breaking or blocks reliable diffing, such as removed endpoints, newly required parameters, removed response codes, removed response fields, type changes, or invalid specs. warning means compatibility drift should be reviewed. info is usually additive.

Limitations

• This actor focuses on practical breaking-change evidence and does not replace a full OpenAPI conformance validator.
• URL fetching is optional and capped; pinned JSON or YAML spec artifacts are the recommended input for reliable CI use.
• Complex $ref graphs, vendor-specific extensions, and every possible schema constraint are not expanded with full compiler-level semantics.
• Results are compatibility triage rows and should be reviewed before production release decisions.

FAQ

Does the actor fetch URLs by default?

No. It is local-first and fixture-first. URL fetching requires allowUrlFetch: true.

Does it support YAML?

It supports JSON and a simple YAML shape suitable for common OpenAPI path/method structures. For maximum fidelity, pass JSON.

Is this a full OpenAPI semantic validator?

No. It includes a lightweight validation helper to catch missing version and paths. Use a dedicated OpenAPI validator in CI if you need full specification compliance.

What counts as breaking?

Removed endpoints, newly required request parameters, removed response codes, removed response fields, response type changes, request body compatibility changes, and invalid specs are treated as critical.

Can I audit multiple APIs in one run?

Does this need a proxy?

No proxy is required for inline specs. URL fetching is optional and intended for simple spec files, not anti-bot pages.

Related Actors

• API Docs Changelog Diff Monitor
• Security Headers Auditor
• TLS Certificate Monitor
• Broken Link Redirect Map
• Structured Data Monitor for AI Search