OpenAPI Integration: Dynamic Routing and OAuth Guard Unification #1410
Conversation
- Added new examples for backend script method calls from `.json` configurations, enhancing practical understanding for developers. - Clarified usage of request parameters and common pitfalls, improving guidance for effective backend script implementation. - Updated existing sections to ensure consistency and clarity in documentation, supporting better developer experience.
- Introduced support for OpenAPI mode, allowing dynamic routing and OAuth guards for API endpoints. - Updated API root path handling to accommodate OpenAPI configurations, ensuring consistent URL structures. - Added well-known routes for Yao metadata and OAuth discovery, improving API discoverability. - Refactored middleware and guards to streamline OpenAPI integration, enhancing overall service functionality. - Removed deprecated agent TypeScript file, simplifying the codebase and improving maintainability.
|
Thank you for the PR! The db: SQLite3 redis: 4 mongo: 6.0 test workflow is running, the results of the run will be commented later. |
|
Thank you for the PR! The db: MySQL8.0 redis: 6 mongo: 6.0 test workflow is running, the results of the run will be commented later. |
|
Thank you for the PR! The db: SQLite3 redis: 6 mongo: 6.0 test workflow is running, the results of the run will be commented later. |
|
Thank you for the PR! The db: SQLite3 redis: 5 mongo: 6.0 test workflow is running, the results of the run will be commented later. |
|
Thank you for the PR! The db: MySQL8.0 redis: 5 mongo: 6.0 test workflow is running, the results of the run will be commented later. |
|
Thank you for the PR! The db: MySQL8.0 redis: 4 mongo: 6.0 test workflow is running, the results of the run will be commented later. |
|
🤖 AI Tests (agent, aigc) running with SQLite... |
|
🤖 KB Tests (kb) running with SQLite... |
|
✅ KB Tests (kb) passed! |
|
✨DONE✨ db: SQLite3 redis: 4 mongo: 6.0 passed. |
|
✨DONE✨ db: SQLite3 redis: 6 mongo: 6.0 passed. |
|
✨DONE✨ db: SQLite3 redis: 5 mongo: 6.0 passed. |
|
✨DONE✨ db: MySQL8.0 redis: 5 mongo: 6.0 passed. |
|
✅ AI Tests (agent, aigc) passed! |
|
✨DONE✨ db: MySQL8.0 redis: 6 mongo: 6.0 passed. |
|
✨DONE✨ db: MySQL8.0 redis: 4 mongo: 6.0 passed. |
1 participant
https://github.com/yaoapp/yao/blob/main/openapi/docs/migration-guide.md
Summary
This PR integrates OpenAPI functionality into the Yao service layer, enabling seamless switching between traditional JWT mode and OpenAPI OAuth mode. Key features include dynamic API routing, hot-reload support, and unified guard mechanism.
Breaking Changes
/apito/{baseURL}(e.g.,/v1)/{baseURL}/api/*/{baseURL}/__yao/*Key Changes
GOU Layer
RouteTable,FindHandler(),BuildRouteTable()for runtime route lookupReloadAPIs()to reload API definitions without restartBuildHandler()for dynamic handler buildinggetAuthorizedInfo()now supports both__authorizedmap and individual context fields (__subject,__scope, etc.)YAO Layer
OpenAPIGuards()returns OAuth guards when OpenAPI is enabled, directly usingoauth.OAuth.GuardDynamicAPIHandlerproxies developer API requests with hot-reload supportReloadAPIs()instead ofRestart()in OpenAPI modeRunnow passes authorized info to V8 context/.well-known/yaofor client-side configuration discoveryACL Layer
RequiredScopescorrectlyexpandUserScopes()now recursively expands nested aliases__yao/*(built-in) andapi/*(developer)Frontend (CUI)
getApiBase()fromwellknown.ts/.well-known/yaofetched synchronously at startup/api/paths throughoutMigration Guide (v0 → v1)
1. Enable OpenAPI
Add
openapi.yaoconfiguration to your app root.2. Update API Paths
/api/your-endpoint/v1/api/your-endpoint/api/__yao/app/setting/v1/__yao/app/setting3. Guard Compatibility
No changes needed. Existing guards (
bearer-jwt,cookie-jwt, etc.) automatically map to OAuth when OpenAPI is enabled.4. Scope Configuration
Add scope files for your custom APIs:
openapi/scopes/__yao/yao.yml
__yao:yao:execute:all:
endpoints:
- GET /__yao/*
- POST /__yao/*
openapi/scopes/api/api.yml
api:api:execute:all:
endpoints:
- GET /api/*
- POST /api/*