Skip to content

docs: correct Admin API schema metadata - #14206

Open
kayx23 wants to merge 1 commit into
apache:masterfrom
kayx23:docs/fix-admin-api-generation
Open

kayx23 wants to merge 1 commit into
apache:masterfrom
kayx23:docs/fix-admin-api-generation

Conversation

@kayx23

@kayx23 kayx23 commented Nov 16, 2026

Copy link
Copy Markdown
Member

Summary

  • restore the manager-specific SecretPatch schemas and nullable merge-patch fields
  • document closed enum values for hashing, upstream schemes, host forwarding, route status, and SSL status/type
  • describe the four built-in upstream balancers while keeping Upstream.type open for user-defined balancer modules
  • declare intentionally unconstrained array items explicitly and validate this in the Admin API contract checker
  • add regression coverage for the generated metadata and regenerate admin-api.json

Why

The modular Admin API source generated a valid OpenAPI 3.1 document, but it dropped schema detail that the reference renderer and downstream quality checks rely on. In particular, the generated SecretPatch became an unstructured object, several enums lost their descriptions, and unconstrained arrays omitted items entirely.

Upstream.type is intentionally not converted to an enum: APISIX has supported user-defined balancers since #4605. The description lists the built-in implementations without closing the field to extensions.

Validation

  • make bundle-admin-api-spec
  • python -m unittest discover -s t/openapi -v (20 tests)
  • python utils/validate-admin-api.py
  • python utils/validate-control-api.py
  • Spectral 6.16.2 with the downstream APISIX Admin API ruleset: 0 errors
  • git diff --check

@kayx23 kayx23 changed the title docs: restore Admin API schema metadata docs: complete Admin API schema metadata Nov 16, 2026
@kayx23 kayx23 changed the title docs: complete Admin API schema metadata docs: correct Admin API schema metadata Nov 16, 2026
@kayx23
kayx23 force-pushed the docs/fix-admin-api-generation branch from 956e3ce to 1f78959 Compare November 16, 2026 04:53
@kayx23
kayx23 force-pushed the docs/fix-admin-api-generation branch from 1f78959 to e916a54 Compare November 16, 2026 05:02
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant