[kayx23]

Summary

• add a version-appropriate OpenAPI 3.1 contract for the release/3.16 Admin API
• validate the operation surface, source schemas, internal references, examples, and defaults from checked-in files
• document the supported header, query, and cookie authentication alternatives and HTTPS listener prerequisites
• replace the remaining API7-specific metadata and link with a version-pinned Apache reference
• rebase the contract onto the merged 3.16 CI stabilization from ci: stabilize release/3.16 CI environment #14095

Why this is needed

The 3.16 Admin API documentation has no machine-readable contract that the website can render independently for this release. Copying a newer contract would be inaccurate because operations, schemas, defaults, and examples differ across release branches. This specification was therefore verified against the checked-in 3.16 source and keeps 3.16-specific behavior.

The CI prerequisite is intentionally separate: #14095 stabilizes the historical branch environment, while this PR contains only the OpenAPI contract and its offline validator.

Validation

• one clean commit containing only the specification and validation files
• offline checker passes with OpenAPI 3.1.0, APISIX 3.16.0, 98 operations, 896 internal references, and unique operation IDs and exact path parameters
• source parity passes for 11 native resource/request schemas and 3 secret manager schemas
• 2,294 schema checks, 614 example/default validations, and 92 default-value checks pass
• Redocly reports a valid OpenAPI document
• git diff --check origin/release/3.16...HEAD
• 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.