[Interoperability] Add machine-readable OpenAPI and AsyncAPI contracts

[seonghobae]

Buyer-visible / integration gap

mightyETL now has canonical prose API/event documentation in PR #149, but protected develop@622e5e6c3d534f230c390f10e3832efadfc01825 has no checked-in machine-readable OpenAPI or AsyncAPI contract and no SpringDoc/OpenAPI generator dependency. A buyer, SDK generator, gateway integrator, contract-test harness, or event consumer therefore still has to infer schemas from Java controllers and prose.

This is intentionally separate from #149 so the already-large canonical-documentation baseline is not expanded after a branch-writer conflict.

Standards baseline

At implementation time reverify the latest final published specifications from the official projects. As of the issue creation evidence:

• OpenAPI Initiative lists OpenAPI Specification 3.2.0 as its latest published OAS (https://spec.openapis.org/oas/latest.html / v3.2.0, published 2025-09-19);
• AsyncAPI documentation and release material expose the 3.1.0 specification generation for event-driven API documents (https://www.asyncapi.com/docs/reference and current 3.1.0 release/tutorial material).

Do not use a draft/editor version merely because it is newer than the latest final published specification.

Required product boundary

HTTP

Generate or maintain a validated OpenAPI document for protected shipped endpoints only, including at minimum:

• POST /api/etl/process;
• GET /api/etl/connectors;
• feature-gated POST /api/etl/jobs;
• feature-gated owner-scoped GET /api/etl/jobs/{jobRecordId};
• POST /api/cdc/start;
• POST /api/cdc/stop;
• GET /api/cdc/status;
• GET /api/cdc/sources;
• GET /api/cdc/targets;
• RFC 9457 problem representations;
• Idempotency-Key, Idempotency-Replayed, Location, Cache-Control, and relevant content types/statuses.

Active-PR endpoints/states such as pagination, Retry-After, ETag, cancellation, replay, or JWT mode must be included only on the integration PR that actually ships them; they must not be promoted to the protected baseline spec early.

Events

Add an AsyncAPI contract for the live CDC publication boundary that truthfully describes raw Debezium JSON compatibility, destination/topic semantics, key optionality, Kafka transport, and replay-tolerant delivery semantics. Do not call the event exactly-once or canonicalized while protected source does not prove those claims.

TDD / validation requirements

• RED contract test first: machine-readable specs absent or stale relative to live controller/event contracts;
• validate OpenAPI/AsyncAPI documents against pinned validators/schemas;
• contract tests compare checked-in paths, HTTP methods, status codes, headers, and bounded representative schemas against live controllers;
• negative test proves active_pr routes/states cannot appear in a protected-develop published contract before integration;
• generated SDK/client smoke test for at least one supported language, or a documented reason for keeping validation generator-neutral;
• Kafka message fixture validates the AsyncAPI schema against actual protected live publication payload/key shape;
• documentation links spec artifacts from README/API contract/Architecture/Traceability;
• exact-current-head CI/security/coverage/review evidence required before merge.

Compatibility / rollback

• public contract changes require semantic compatibility review and changelog entry;
• if runtime-generated docs are used, the build must deterministically compare them with checked-in canonical artifacts or publish them from the exact release head;
• rollback cannot leave a published machine-readable contract advertising endpoints/states absent from the rolled-back binary.

References to record in doctoring — APA 7th style

OpenAPI Initiative. (2025). OpenAPI Specification 3.2.0. https://spec.openapis.org/oas/v3.2.0.html

AsyncAPI Initiative. (2026). AsyncAPI Specification. https://www.asyncapi.com/docs/reference

RFC 9110, RFC 9457, and RFC 9651 remain the HTTP/problem/idempotency field semantic references already used by mightyETL.

[seonghobae]

Fresh execution evidence for the active machine-readable-contract lane:

• PR feat(api): add machine-readable HTTP and CDC contracts #157 live source head is aa558f25363bfb833e49ed79b49cfdbea39c8eea on unchanged protected develop@622e5e6c3d534f230c390f10e3832efadfc01825; the PR body still names an older head and is stale evidence.
• On that live source identity, Dependency Review 31315084615, SBOM 31315084635, CI 31315084630, and Security Scan 31315084626 completed successfully. SAST Semgrep 31315084629 failed.
• The Semgrep job checked out synthetic integration revision 95579e529a677fe70209cb6abd56f86bc628a89d and reported exactly one unsuppressed blocking finding: yaml.openapi.security.use-of-basic-authentication.use-of-basic-authentication at contracts/openapi/mightyetl.yaml, against the truthful basicAuth scheme.

RCA: this is not an OpenAPI syntax defect. Protected etl-service really uses HTTP Basic on /api/**; issue #161 owns replacing that direct-service trust boundary. Removing basicAuth from the contract, inventing OAuth/OIDC/mTLS before protected implementation, suppressing the Semgrep rule, or blindly rerunning the unchanged scan would make the interface evidence less truthful rather than fix the product.

Classification: the SAST gate is defer_until_trigger for #157 until the protected ETL authentication boundary changes under #161 or an equivalent accepted implementation, at which point the contract and SAST evidence must be regenerated together. Source mutation on #157 is also branch-locally frozen for this invocation because the live head moved under another writer. The other aggregate greens remain integration-preview evidence and do not waive literal-source identity, scanner-completeness (#196), non-vacuous coverage (#162/#164/#205), or independent-review requirements.

Issue #152 therefore remains open: the checked-in contracts exist on an active PR, but current SAST correctly exposes a protected-product authentication gap and the requested maintained-validator/schema plus representative contract-fixture acceptance still must be completed without weakening truthful security metadata.