Uh oh!
There was an error while loading. Please reload this page.
docs(admin): expand OpenAPI document to cover every mounted route - #96
Merged
Conversation
The hand-written OpenAPI document was stuck at the original two resources (Models + ApiKeys) — provider_keys, the apikey rotate sub- resource, /admin/v1/health, /playground/chat/completions, and the unauthenticated /health, /metrics, /admin/openapi.json, /admin/openapi-scalar were all missing. Scalar UI loaders look at this JSON to populate the left-hand sidebar, so anyone opening /admin/openapi-scalar in the browser had no way to discover those routes. This commit: - Documents every route mounted in `build_router` (lib.rs line 47-96) - Adds reusable component schemas: Model (with the new display_name/provider/model_name/provider_key_id shape from #95), ApiKey, ProviderKey, RateLimit, Routing, ModelCost, AdminError, plus *Entry wrappers for the response shape `{id, value, revision}` - Marks the four public routes (/health, /metrics, /admin/openapi.*) with `security: []` so Scalar's "Try it" doesn't prompt for an admin key on them - Pins coverage with a unit test that walks every documented path + every reusable schema and fails on first missing entry Bumps the raw-string delimiter from `r#"..."#` to `r##"..."##` because the embedded JSON `$ref` pointers (`"#/components/schemas/Foo"`) collide with the `#` in the closing delimiter. Drive-by README correction: the previous entry overpromised `/admin/v1/guardrails`, `/admin/v1/cache_policies`, `/admin/v1/observability_exporters`, and `/admin/v1/spend` as if they were live admin routes. They aren't — those resources exist as core types and are honoured at runtime, but standalone CRUD over them is direct-etcd-write today. Listed honestly with a one-line "handlers will follow" note. Verified - `cargo fmt --all --check` clean - `cargo clippy --workspace --tests -- -D warnings` clean - `cargo test -p aisix-admin` green (46 passed, includes the two new openapi assertions covering path coverage + public-route security)
ℹ️ Recent review info⚙️ Run configurationConfiguration used: Organization UI Review profile: CHILL Plan: Free Run ID: 📒 Files selected for processing (2)
📝 WalkthroughWalkthroughThis PR expands the OpenAPI specification for the admin API with comprehensive endpoint definitions, schemas, and security schemes. Tests are strengthened to validate spec structure and security properties. README documentation is clarified to distinguish between runtime-honored resource types and standalone mode CRUD availability. ChangesAdmin API Documentation and OpenAPI Spec Update
Estimated code review effort🎯 2 (Simple) | ⏱️ ~10 minutes Note 🎁 Summarized by CodeRabbit FreeYour 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 |
There was a problem hiding this comment.
Pull request overview
Expands the aisix-admin hand-written OpenAPI 3.1 document so the Scalar UI reflects all routes mounted by crates/aisix-admin::build_router, and updates the README to accurately describe which admin resources are actually CRUD-backed today.
Changes:
- Documented all mounted admin/playground/health/metrics routes in
/admin/openapi.jsonand exposed them in Scalar UI. - Added reusable component schemas (Model/ApiKey/ProviderKey/etc.) and OpenAPI unit tests to enforce path/security coverage.
- Corrected README claims about non-existent standalone admin CRUD resources.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 5 comments.
| File | Description |
|---|---|
| README.md | Updates “What’s shipped today” to remove unsupported admin CRUD routes and add a clarification note. |
| crates/aisix-admin/src/openapi.rs | Expands the OpenAPI JSON to cover all mounted routes; adds component schemas and tests for path + public-route security coverage. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Comment on lines
+175
to
+186
| "required": ["display_name"], | ||
| "properties": { | ||
| "display_name": {"type": "string", "example": "my-gpt4"}, | ||
| "provider": {"type": "string", "enum": ["openai","anthropic","gemini","deepseek"]}, | ||
| "model_name": {"type": "string", "example": "gpt-4o"}, | ||
| "provider_key_id": {"type": "string", "example": "11111111-1111-1111-1111-111111111111"}, | ||
| "timeout": {"type": "integer", "minimum": 0, "description": "Request timeout in milliseconds. Absent or 0 = no timeout."}, | ||
| "rate_limit": {"$ref": "#/components/schemas/RateLimit"}, | ||
| "routing": {"$ref": "#/components/schemas/Routing"}, | ||
| "cost": {"$ref": "#/components/schemas/ModelCost"} | ||
| }, | ||
| "description": "A direct model ships `provider` + `model_name` + `provider_key_id`; a routing model ships `routing` and omits the upstream triple." |
Comment on lines
+69
to
+75
| "summary": "create model", | ||
| "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Model"}}}}, | ||
| "responses": { | ||
| "200": {"description": "OK", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ModelEntry"}}}}, | ||
| "400": {"description": "schema validation failed"}, | ||
| "409": {"description": "duplicate display_name"} | ||
| } |
Comment on lines
+81
to
+85
| "put": { | ||
| "summary": "update model", | ||
| "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Model"}}}}, | ||
| "responses": {"200": {"description": "OK"}, "400": {"description": "schema validation failed"}, "404": {"description": "not found"}, "409": {"description": "duplicate display_name"}} | ||
| }, |
| "required": ["key_hash", "allowed_models"], | ||
| "properties": { | ||
| "key_hash": {"type": "string", "description": "SHA-256 hex of the plaintext bearer. Lowercase.", "example": "91ed2dbc407561556f3e7be98ba0bd2a57986d6a868c482d867d19c6d40d201c"}, | ||
| "allowed_models": {"type": "array", "items": {"type": "string"}, "description": "Allowed Model display_names. `[\"*\"]` for all; `[]` denies everything."}, |
| "type": "object", | ||
| "required": ["model"], | ||
| "properties": { | ||
| "model": {"type": "string", "description": "Target Model.display_name"}, |
Uh oh!
There was an error while loading. Please reload this page.
moonming added a commit
that referenced
this pull request
May 7, 2026
…ility_exporters (#97) Brings the standalone Admin API up to parity with the resource types that aisix-core already understands and the gateway already honours at runtime. Before this PR, those three resources existed as snapshot tables and runtime hooks but had no admin endpoint — operators had to hand-write etcd keys to configure them, which is exactly the sharp edge an admin layer is supposed to file off. Adds - `guardrails_handlers.rs`, `cache_policies_handlers.rs`, `observability_exporters_handlers.rs` — same template as `provider_keys_handlers.rs`: validate JSON, reject duplicate name, uuid v4 on POST, bump revision on PUT. - 12 new `ConfigStore` trait methods (4 per resource), implemented on both `InMemoryStore` and `EtcdConfigStore`. - 6 new routes wired into `build_router`: `/admin/v1/guardrails[/:id]` `/admin/v1/cache_policies[/:id]` `/admin/v1/observability_exporters[/:id]` - 3 new etcd subkey constants (`guardrails`, `cache_policies`, `observability_exporters`) — match the kind segments `aisix-etcd::loader` already dispatches on, so writes from the admin path land in the same prefix the watch supervisor reads. - OpenAPI document expanded to include the new paths AND component schemas (`Guardrail`, `CachePolicy`, `ObservabilityExporter`); the forcing-function test from #96 walks the new entries. - Five integration tests covering the happy path + duplicate-name 409 + bad-payload 400 + the loopback-only http endpoint guard on observability exporters. Re-exports `CachePolicy`, `ObservabilityExporter`, `ExporterKind`, `validate_cache_policy`, `validate_observability_exporter` at the `aisix_core` crate root so handlers can name them without reaching into `aisix_core::models::*`. Drive-by: README's "Admin handlers will follow" caveat is gone — the list is now accurate. Verified - `cargo fmt --all --check` clean - `cargo clippy --workspace --tests -- -D warnings` clean - `cargo test -p aisix-admin` green (51 passed; +5 new)
4 tasks
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for freeto join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
The hand-written OpenAPI document at
/admin/openapi.jsonwas stuck at the original two resources (Models + ApiKeys). After PR #95 added ProviderKey, several routes that exist inbuild_routerweren't reflected in the spec — meaning Scalar UI users had no way to discover them.What's documented now
Every route mounted in
crate::build_router(lib.rslines 47–96):/health— process health + snapshot counts/metrics— Prometheus/admin/openapi.json+/admin/openapi-scalar— self-references/admin/v1/models— CRUD/admin/v1/apikeys— CRUD +POST .../rotate/admin/v1/provider_keys— CRUD/admin/v1/health— per-Model upstream health/playground/chat/completions— proxy in-processReusable schemas added
Model(new shape:display_name+provider+model_name+provider_key_id),ApiKey,ProviderKey,RateLimit,Routing,ModelCost,AdminError, plusModelEntry/ApiKeyEntrywrappers for the{id, value, revision}response envelope.Public-route security
/health,/metrics,/admin/openapi.json,/admin/openapi-scalarare marked withsecurity: []so Scalar's "Try it" doesn't prompt for an admin key on them. Mirrors the design comment inlib.rs("OpenAPI scalar UI is unauthenticated like /metrics").Drive-by: README correction
The previous README overpromised
/admin/v1/guardrails,/admin/v1/cache_policies,/admin/v1/observability_exporters, and/admin/v1/spendas if those were live admin routes. They aren't — those resources exist as core types and are honoured at runtime, but standalone CRUD goes through direct etcd writes today. Listed accurately with a one-line "handlers will follow" note.Test plan
cargo fmt --all --checkcleancargo clippy --workspace --tests -- -D warningscleancargo test -p aisix-admingreen (46 passed; includes two new openapi assertions: path coverage + public-route security)Summary by CodeRabbit
Documentation
Tests