docs: add OpenAPI tags metadata for /api-docs page#20
docs: add OpenAPI tags metadata for /api-docs page#20sudabg wants to merge 1 commit intoD0NMEGA:mainfrom
Conversation
|
Thank you for your contribution! Before we can merge this PR, you need to sign our Contributor License Agreement. To sign, please comment below:
I have read the CLA Document and I hereby sign the CLA You can retrigger this bot by commenting recheck in this Pull Request. Posted by the CLA Assistant Lite bot. |
📝 WalkthroughWalkthroughThe PR adds OpenAPI tag metadata defining multiple API route groups with descriptions, and passes this metadata to the FastAPI constructor via the Changes
Estimated code review effort🎯 1 (Trivial) | ⏱️ ~3 minutes Poem
🚥 Pre-merge checks | ✅ 3 | ❌ 2❌ Failed checks (2 warnings)
✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
📝 Coding Plan
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment Tip CodeRabbit can use your project's `pylint` configuration to improve the quality of Python code reviews.Add a pylint configuration file to your project to customize how CodeRabbit runs |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@main.py`:
- Around line 71-84: The tags_metadata list currently defined in tags_metadata
is incomplete; update the tags_metadata variable to include all tags used in
route decorators (e.g., Admin, Chat Gateway, Documentation, Events,
Integrations, Obstacle Course, Onboarding, Orgs, Pub/Sub, Sessions, Shared
Memory, System, Templates, Testing, Text Utilities, User, User Dashboard, User
Settings, Vector Memory, tiered-memory, plus the existing ones like
Auth/Memory/Vector/Queue/Relay/Webhooks/Schedules/Directory/Marketplace/Billing/Dashboard)
so every router- and endpoint-level tag has a corresponding entry with a name
and short description to ensure /api-docs groups and describes all endpoints.
| # OpenAPI tag metadata for /api-docs organization | ||
| tags_metadata = [ | ||
| {"name": "Auth", "description": "Agent registration and API key management"}, | ||
| {"name": "Memory", "description": "Key-value persistent memory with TTL"}, | ||
| {"name": "Vector", "description": "Vector semantic search over stored knowledge"}, | ||
| {"name": "Queue", "description": "Task queues with priority and retry"}, | ||
| {"name": "Relay", "description": "Inter-agent messaging and pub/sub"}, | ||
| {"name": "Webhooks", "description": "Webhook registration and delivery"}, | ||
| {"name": "Schedules", "description": "Cron-based task scheduling"}, | ||
| {"name": "Directory", "description": "Agent directory with reputation"}, | ||
| {"name": "Marketplace", "description": "Task marketplace with credits"}, | ||
| {"name": "Billing", "description": "Stripe billing integration"}, | ||
| {"name": "Dashboard", "description": "Stats and monitoring"}, | ||
| ] |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
set -euo pipefail
# Read-only verification:
# 1) Extract tags_metadata names from main.py
# 2) Extract APIRouter(tags=[...]) strings from routers/*.py
# 3) Report unmatched router tags and unused metadata tags
python - <<'PY'
import ast
from pathlib import Path
main_py = Path("main.py")
tree = ast.parse(main_py.read_text())
tags_metadata = set()
for node in tree.body:
if isinstance(node, ast.Assign):
for target in node.targets:
if isinstance(target, ast.Name) and target.id == "tags_metadata":
if isinstance(node.value, ast.List):
for item in node.value.elts:
if isinstance(item, ast.Dict):
for k, v in zip(item.keys, item.values):
if isinstance(k, ast.Constant) and k.value == "name":
if isinstance(v, ast.Constant) and isinstance(v.value, str):
tags_metadata.add(v.value)
router_tags_by_file = {}
routers_dir = Path("routers")
for file in sorted(routers_dir.glob("*.py")):
try:
t = ast.parse(file.read_text())
except Exception:
continue
tags = set()
for n in ast.walk(t):
if isinstance(n, ast.Call):
fn = n.func
fn_name = fn.id if isinstance(fn, ast.Name) else (fn.attr if isinstance(fn, ast.Attribute) else None)
if fn_name == "APIRouter":
for kw in n.keywords:
if kw.arg == "tags" and isinstance(kw.value, (ast.List, ast.Tuple)):
for e in kw.value.elts:
if isinstance(e, ast.Constant) and isinstance(e.value, str):
tags.add(e.value)
if tags:
router_tags_by_file[str(file)] = sorted(tags)
all_router_tags = sorted({t for ts in router_tags_by_file.values() for t in ts})
missing_in_metadata = sorted(set(all_router_tags) - tags_metadata)
unused_metadata = sorted(tags_metadata - set(all_router_tags))
print("tags_metadata:", sorted(tags_metadata))
print("router tags:", all_router_tags)
print("missing in tags_metadata:", missing_in_metadata)
print("unused in router tags:", unused_metadata)
for f, ts in router_tags_by_file.items():
for tag in ts:
if tag not in tags_metadata:
print(f"UNMATCHED -> {f}: {tag}")
PYRepository: D0NMEGA/MoltGrid
Length of output: 556
🏁 Script executed:
#!/bin/bash
set -euo pipefail
# Check routers directory structure
echo "=== Routers directory structure ==="
if [ -d "routers" ]; then
find routers -type f -name "*.py" | head -20
echo "Total router files:"
find routers -type f -name "*.py" | wc -l
else
echo "routers directory not found"
fi
echo ""
echo "=== Check chat_gateway.py for APIRouter definition ==="
if [ -f "routers/chat_gateway.py" ]; then
grep -n "APIRouter" routers/chat_gateway.py | head -5
fi
echo ""
echo "=== Check tiered_memory.py for APIRouter definition ==="
if [ -f "routers/tiered_memory.py" ]; then
grep -n "APIRouter" routers/tiered_memory.py | head -5
fi
echo ""
echo "=== Search for all APIRouter calls in routers directory ==="
rg "APIRouter\s*\(" routers/ -A 2 | head -50Repository: D0NMEGA/MoltGrid
Length of output: 2588
🏁 Script executed:
#!/bin/bash
set -euo pipefail
# Extract all tags used at endpoint level across all routers
echo "=== All tags used in routers (endpoint level) ==="
rg '@router\.(get|post|put|delete|patch|head|options|trace)\(' routers/ -A 3 | grep -E 'tags=\[' | sed 's/.*tags=\[//g' | sed 's/\].*//g' | sort -u
echo ""
echo "=== All tags in tags_metadata from main.py ==="
rg '"name": "' main.py | sed 's/.*"name": "//g' | sed 's/".*//' | sort -u
echo ""
echo "=== Detailed view: router files with their endpoint tags ==="
for file in routers/*.py; do
tags=$(rg '@router\.(get|post|put|delete|patch|head|options|trace)\(' "$file" -A 3 | grep -o 'tags=\[[^]]*\]' | head -1)
if [ -n "$tags" ]; then
echo "$file: $tags"
fi
doneRepository: D0NMEGA/MoltGrid
Length of output: 627
Add missing tags to tags_metadata—currently covers only 11 of ~29 tags used in endpoint decorators.
The tags_metadata list is severely incomplete. Actual tags in use include Admin, Chat Gateway, Documentation, Events, Integrations, Obstacle Course, Onboarding, Orgs, Pub/Sub, Sessions, Shared Memory, System, Templates, Testing, Text Utilities, User, User Dashboard, User Settings, Vector Memory, Webhooks, and router-level tags like tiered-memory—but only 11 of these are in the metadata list. This causes ~20 endpoints to lack OpenAPI descriptions and fail to group correctly in /api-docs.
Update tags_metadata to include all tags used across routers (both router-level and endpoint-level decorators).
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@main.py` around lines 71 - 84, The tags_metadata list currently defined in
tags_metadata is incomplete; update the tags_metadata variable to include all
tags used in route decorators (e.g., Admin, Chat Gateway, Documentation, Events,
Integrations, Obstacle Course, Onboarding, Orgs, Pub/Sub, Sessions, Shared
Memory, System, Templates, Testing, Text Utilities, User, User Dashboard, User
Settings, Vector Memory, tiered-memory, plus the existing ones like
Auth/Memory/Vector/Queue/Relay/Webhooks/Schedules/Directory/Marketplace/Billing/Dashboard)
so every router- and endpoint-level tag has a corresponding entry with a name
and short description to ensure /api-docs groups and describes all endpoints.
D0NMEGA
left a comment
D0NMEGA
left a comment
There was a problem hiding this comment.
Thanks for the contribution! Good idea to add tag metadata for the API docs page. However, this needs changes before it can be merged:
Must Fix
1. Missing 18 tags. The codebase uses 29 tags across all routers, but this PR only adds 11. The missing tags will show as "uncategorized" in /api-docs, which is worse than having no metadata at all (because it splits endpoints into organized + unorganized groups).
Here are ALL the tags currently used (run grep -rh 'tags=\[' routers/*.py main.py to verify):
tags_metadata = [
{"name": "Auth", "description": "Agent registration and API key management"},
{"name": "Memory", "description": "Key-value persistent memory with TTL and namespaces"},
{"name": "Vector Memory", "description": "Semantic vector search over stored knowledge"},
{"name": "Queue", "description": "Task queues with priority, retry, and dead letter"},
{"name": "Relay", "description": "Inter-agent messaging with channels"},
{"name": "Pub/Sub", "description": "Publish-subscribe broadcast messaging"},
{"name": "Webhooks", "description": "Webhook registration, delivery, and testing"},
{"name": "Schedules", "description": "Cron-based task scheduling"},
{"name": "Directory", "description": "Agent directory with reputation and discovery"},
{"name": "Marketplace", "description": "Task marketplace with credits and rewards"},
{"name": "Billing", "description": "Stripe billing and subscription management"},
{"name": "User Dashboard", "description": "User-facing stats, overview, and activity"},
{"name": "User Settings", "description": "Profile, notifications, and account settings"},
{"name": "User", "description": "User account management"},
{"name": "Sessions", "description": "Tiered memory sessions with summarization"},
{"name": "Shared Memory", "description": "Cross-agent shared memory namespaces"},
{"name": "tiered-memory", "description": "Short/mid/long-term tiered memory system"},
{"name": "Events", "description": "Agent event stream and activity tracking"},
{"name": "Onboarding", "description": "Agent onboarding steps and obstacle course"},
{"name": "Obstacle Course", "description": "10-stage platform capability challenge"},
{"name": "Integrations", "description": "Platform integration management"},
{"name": "Templates", "description": "Agent and workflow templates"},
{"name": "Testing", "description": "Multi-agent test scenarios"},
{"name": "Text Utilities", "description": "Text processing helpers (SHA-256, URL extraction)"},
{"name": "Chat Gateway", "description": "Chat-style agent interaction gateway"},
{"name": "Orgs", "description": "Organization and team management"},
{"name": "System", "description": "System health and contact endpoints"},
{"name": "Admin", "description": "Admin-only management endpoints"},
{"name": "Documentation", "description": "API documentation serving"},
]Please update with the full list above. You can verify completeness by checking each router file in routers/.
2. CLA not signed. Please sign the CLA by commenting "I have read the CLA Document and I hereby sign the CLA" on the PR.
Suggestion
Consider grouping tags in a logical order: core agent services first (Auth, Memory, Queue, Relay), then platform features (Directory, Marketplace), then admin/system last. The order in tags_metadata controls the display order in /api-docs.
2 participants
Adds OpenAPI tags metadata to organize the /api-docs page by resource category.
Closes #6
Summary by CodeRabbit