refactor(admin): merge resource JSON Schemas into served OpenAPI doc

[moonming]

Stacked on #308 (which is stacked on #307). Base will switch to main once #308 merges.

Summary

Cuts the schema-duplication tail in crates/aisix-admin/src/openapi.rs. Resource shapes (Model, ApiKey, ProviderKey, Guardrail, CachePolicy, ObservabilityExporter, RateLimit, Routing) are no longer hand-written inside the OpenAPI document — they are pulled at compile time from the canonical files schemas/resources/*.schema.json (generated by dump-schema in #308, drift-guarded by CI in #309) and merged into the served spec at first request.

Before / After

	Before	After
Sources of truth for resource shape	Rust struct + inline OpenAPI + AISIX-Cloud + dashboard form	Rust struct only
Guardrail kind discrimination	additionalProperties: true + comment	oneOf with proper sub-schemas
Provider enum	Hand-listed 6 variants	Generated from Rust enum
Adapter enum (#302 Phase A)	Not present	Generated, kebab-case
Nested types (ParamConstraints, TelemetryTags, etc.)	Missing	Hoisted to components.schemas
Component schema count	17	33

Implementation sketch

const RESOURCE_SCHEMAS: &[(&str, &str)] = &[
    ("Model",       include_str!("../../../schemas/resources/model.schema.json")),
    ("ApiKey",      include_str!("../../../schemas/resources/api_key.schema.json")),
    // ... 8 total
];

fn merged_openapi() -> &'static str {
    static CELL: OnceLock<String> = OnceLock::new();
    CELL.get_or_init(|| {
        let mut doc: Value = serde_json::from_str(OPENAPI_JSON_BASE).unwrap();
        for (name, raw) in RESOURCE_SCHEMAS {
            let mut schema: Value = serde_json::from_str(raw).unwrap();
            // 1. hoist `definitions/*` into top-level `components.schemas/*`
            // 2. strip `$schema` / `title`
            // 3. place under `components.schemas.<name>`
            ...
        }
        // rewrite `$ref: #/definitions/X` → `$ref: #/components/schemas/X`
        rewrite_definitions_refs(&mut doc);
        serde_json::to_string(&doc).unwrap()
    })
}

Full diff: +148 / −141 across the one file.

Verification

• cargo check -p aisix-admin clean
• cargo clippy --workspace --all-targets -- -D warnings clean
• cargo fmt --all -- --check clean
• cargo test -p aisix-admin --lib — all 7 openapi tests pass, including openapi_apikey_schema_excludes_max_budget_usd (regression test against managed-mode field leak)
• External reference audit: parsed the merged doc, found 43 $ref references across 32 distinct targets, 0 unresolved. Every reference inside the served spec is locally resolvable — Scalar UI never needs to fetch anything external.

Behavior change

The served /admin/openapi.json body is materially different (more precise types, more nested definitions surfaced). Wire path / status codes / auth / error envelope are unchanged. Scalar UI keeps working at /admin/openapi-scalar unchanged.

What this does NOT do

• Does not upgrade schemars 0.8 → 1.x. Output stays draft-07; OpenAPI 3.1 tolerates this for inline schemas, but a future upgrade is worth tracking (separate issue).
• Does not touch the path definitions (/admin/v1/*). Those are still hand-maintained in OPENAPI_JSON_BASE (formerly OPENAPI_JSON).
• Does not change the proxy /v1/chat/completions surface — out of scope per existing module-level comment ("operators refer to OpenAI's published spec").

Stack

Builds on:

• chore(core): derive JsonSchema on resource types #307 (chore(core): derive JsonSchema on resource types)
• chore(core): add dump-schema binary and commit canonical schemas #308 (chore(core): add dump-schema binary and commit canonical schemas)
• ci: add schema drift check for resource JSON Schemas #309 (ci: add schema drift check for resource JSON Schemas)

Merge order: #307 → #308 → #309 → this PR.

Refs #304 (#1).

[coderabbitai]

Warning

Rate limit exceeded

@moonming has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 3 minutes and 1 second before requesting another review.

You’ve run out of usage credits. Purchase more in the billing tab.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Free

Run ID: acd781c4-964a-4f2c-ae42-7ea99c6003a7

📥 Commits

Reviewing files that changed from the base of the PR and between 36ed90b and 13bcf9c.

📒 Files selected for processing (3)

• Dockerfile
• crates/aisix-admin/src/lib.rs
• crates/aisix-admin/src/openapi.rs

---

Note

🎁 Summarized by CodeRabbit Free

Your organization has reached its limit of developer seats under the Pro Plan. For new users, CodeRabbit will generate a high-level summary and a walkthrough for each pull request. For a comprehensive line-by-line review, please add seats to your subscription by visiting https://app.coderabbit.ai/login.If you believe this is a mistake and have available seats, please assign one to the pull request author through the subscription management page using the link above.

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[Copilot]

Copilot encountered an error and was unable to review this pull request. You can try again by re-requesting a review.

[Copilot]

Copilot encountered an error and was unable to review this pull request. You can try again by re-requesting a review.