[kayx23]

Dependency

The CI prerequisite #14094 and terminology prerequisite #14110 have merged. This branch is rebased onto the resulting release/3.17 head. Unrelated flaky product-test checks are not part of this documentation PR's scope.

Why this contract is needed

• release/3.17 does not have a checked-in canonical OpenAPI contract for its Admin API.
• Reusing a newer branch's document would misrepresent the 3.17 operation surface, schemas, defaults, or examples.
• The contract previously carried API7-specific metadata and links; Apache APISIX should own the canonical source used by downstream documentation.
• A fail-closed offline checker is needed to detect source and schema drift without depending on a running gateway.

Summary

• add a version-appropriate OpenAPI 3.1 contract for the 3.17 Admin API
• validate local references, operation IDs, path parameters, schemas, examples, defaults, resource methods, and reviewed source hashes
• replace API7-specific metadata, links, and examples with version-pinned Apache references
• consume the corrected terminology merged in docs: backport terminology corrections to 3.17 #14110

Validation

• one commit containing only the OpenAPI contract and offline checker inputs
• offline source and schema checker passes with 98 operations, 321 examples, and 120 defaults
• Redocly reports a valid OpenAPI document
• git diff --check origin/release/3.17...HEAD
• all Apache documentation targets return HTTP 200
• the checker fails closed under Python optimization
• the specification contains no API7-specific literals

[kayx23]

CI note: the failing legacy jobs stop before this documentation change or its contract checker runs. The release-branch workflows now execute on Ubuntu 26.04, where actions/setup-python cannot provide Python 3.9 and apt no longer provides libpcre3/libpcre3-dev. The documentation, license, and PR-title checks pass. The version-specific offline OpenAPI source-parity checker and its regression tests also pass locally in a clean isolated environment; validation details are included in the PR description.