kayx23 opened a new pull request, #14160: URL: https://github.com/apache/apisix/pull/14160
## Why The master Admin API OpenAPI contract still disagrees with the current runtime in four related areas: - two inline Consumer response schemas retain a 100-character username limit while the runtime allows 256 characters - SSL inputs reject supported `$secret://` and `$env://` certificate/key references, and the write-response schema represents stored keys as input PEM - Route, Service, Upstream, and Stream Route responses reuse input Upstream schemas even though stored `tls.client_key` values can be encrypted - derived Upstream PATCH and configuration-validation schemas omit current fields and values, including `tls.ca_certs`, slow start, Kubernetes discovery cluster IDs, and `ws`/`wss`, and retain obsolete verification wording These mismatches can make generated clients reject valid configuration, accept invalid direct TLS references, or misrepresent stored responses and partial updates. ## Contract corrections | Area | Correction | | --- | --- | | Consumer responses | Change the two stale inline username limits from 100 to 256 characters. | | SSL inputs | Model PEM values and supported secret/environment references as distinct alternatives for certificates, keys, arrays, and client CA values. | | Direct Upstream TLS | Keep direct client certificates, keys, and CA lists PEM-only and reject secret/environment references, matching runtime validation. | | Stored responses | Add read variants for Route, Service, Upstream, and Stream Route resources, plus a stored SSL write variant, so encrypted private-key values are not validated as input PEM. | | Derived Upstream shapes | Add `ca_certs`, `warm_up_conf`, `discovery_args.cluster_ids`, `ws`/`wss`, and current verification semantics to PATCH and standalone validation schemas. | | PATCH semantics | Add a nullable slow-start patch schema so individual slow-start fields can be merged or removed without requiring a complete replacement object. | Master already contains the Stream Route protocol, active health-check request fields, nonempty health-check status lists, current primary resource-name limits, and key-free SSL GET responses. This PR does not duplicate those 3.19-specific corrections. ## Reviewing the modular source Review the changed files under `docs/openapi/admin-api/components/schemas/` and `docs/openapi/admin-api/paths/`. The self-contained `docs/en/latest/admin-api.json` file is generated with: ```shell make bundle-admin-api-spec ``` ## Source verification Re-audited against the current master runtime schemas, Admin API encryption and filtering paths, SSL secret-reference handling, Upstream validation, and the modular OpenAPI source. Direct Upstream TLS references remain invalid because the runtime parses those fields as PEM; SSL resource references remain supported because SSL validation preserves and resolves them through the secret subsystem. ## Validation - bundled 197 modular YAML files into the self-contained JSON document - generated the bundle twice and confirmed byte-identical output - preserved 47 paths and 104 operations; resolved all 770 internal references - recursively compared Route, Service, Upstream, and SSL patch fields and enums with the current runtime schemas - verified standalone Upstream validation includes the current runtime fields and enum values - validated 256/257-character Consumer response boundaries - validated SSL PEM/reference alternatives and PEM-only direct Upstream TLS inputs - validated stored plaintext/encrypted private-key response shapes and key-free SSL GET responses - validated `ca_certs`, `ws`/`wss`, Kubernetes cluster IDs, and partial slow-start PATCH cases - Redocly: valid document - bundle script: `bash -n` - `git diff --check` -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
