feat: Generate and publish API documentation for core services#176
Conversation
|
@agsaru is attempting to deploy a commit to the s3dfx-cyber's projects Team on Vercel. A member of the Team first needs to authorize it. |
📝 WalkthroughWalkthroughBoth FastAPI services now advertise API-key security and richer OpenAPI metadata, a new workflow publishes generated docs to GitHub Pages, and both service READMEs describe the docs URLs and authorization steps. ChangesOpenAPI Documentation and GitHub Pages Publishing
Estimated code review effort: 3 (Moderate) | ~25 minutes Suggested labels: Suggested reviewers: 🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
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 |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 3
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
services/analyzer/app.py (1)
210-226:⚠️ Potential issue | 🟠 MajorHeader parameter required state bypasses documented 401/403 error contract.
At line 225,
x_api_key: Annotated[str, Header(...)]is marked required. FastAPI validates this parameter during dependency resolution before executing the endpoint function, so missing headers return 422 (validation error) instead of allowingsecurity.require_auth()to return the documented 401/403 errors.Change the header to optional and retrieve it via the Security dependency instead:
Suggested fix
`@app.post`( "/v1/analyze", response_model=AnalysisResponse, tags=["Analysis"], summary="Analyze Prompt", description="Analyzes a given prompt for security threats using both heuristic rules and ML-based detection. Requires a valid API key.", responses={ 401: {"model": ErrorResponse, "description": "Invalid API key"}, 403: {"model": ErrorResponse, "description": "Insufficient permissions"}, 429: {"model": ErrorResponse, "description": "Rate limit or quota exceeded"} }, - dependencies=[Security(api_key_scheme)] ) async def analyze_prompt( request: AnalysisRequest, - x_api_key: Annotated[str, Header(...)] + x_api_key: Annotated[Optional[str], Security(api_key_scheme)] ):Note: Update
require_auth()call to handle the now-optional header value.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@services/analyzer/app.py` around lines 210 - 226, The x_api_key header parameter in the analyze_prompt function is currently marked as required, causing FastAPI to return a 422 validation error for missing headers before the Security dependency can validate it and return the documented 401/403 errors. Change the x_api_key header parameter from required to optional by modifying its type annotation, then update the require_auth() call within the endpoint to handle the now-optional header value appropriately. This allows the Security dependency and require_auth() function to control the validation response and return the correct 401/403 error codes as documented in the endpoint's responses specification.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In @.github/publish-doc.yml:
- Around line 69-77: The "Create Landing Page" step is attempting to interpolate
the page_url output from steps.deployment, but this output is not yet available
since the "Deploy to GitHub Pages" step executes later in the workflow. This
causes the Swagger URLs in lines 69 and 76 to resolve to empty strings,
resulting in invalid links. Move the HTML file generation that creates the
landing page with the Swagger URL references to execute after the "Deploy to
GitHub Pages" step completes, so the page_url output is available for proper
interpolation. Alternatively, regenerate the index.html file in a separate step
that runs after deployment.
- Around line 86-89: Replace the `actions/upload-artifact@v7.0.1` action with
`actions/upload-pages-artifact` in the Upload artifact step. The
`actions/upload-pages-artifact` action automatically handles the required gzip
archive format and names the artifact as `github-pages`, which is necessary for
the subsequent `actions/deploy-pages@v5` deployment to succeed. Make this change
at the location shown (lines 86-89) and also apply the same replacement at the
other Upload artifact step mentioned at lines 91-93 in the same file.
In `@services/ingest/app.py`:
- Around line 332-346: Multiple route handlers use `x_api_key: str =
Header(...)` as a function parameter, which causes FastAPI to validate the
header as required before the handler runs, triggering a 422 response for
missing headers instead of allowing the security logic to return 401/403 as
documented. Replace the `Header(...)` parameter with `Security(api_key_scheme)`
in the ingest_llm_event function and in all other affected handlers (at lines
456-472, 506-521, 544-557, 594-606, and 616-628) to let the security scheme with
`auto_error=False` handle the validation and pass the header value (or None)
directly to the handler for proper error handling.
---
Outside diff comments:
In `@services/analyzer/app.py`:
- Around line 210-226: The x_api_key header parameter in the analyze_prompt
function is currently marked as required, causing FastAPI to return a 422
validation error for missing headers before the Security dependency can validate
it and return the documented 401/403 errors. Change the x_api_key header
parameter from required to optional by modifying its type annotation, then
update the require_auth() call within the endpoint to handle the now-optional
header value appropriately. This allows the Security dependency and
require_auth() function to control the validation response and return the
correct 401/403 error codes as documented in the endpoint's responses
specification.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro Plus
Run ID: 58edfc6e-0b16-4dc0-99d8-5832ff5824f7
📒 Files selected for processing (5)
.github/publish-doc.ymlservices/analyzer/README.mdservices/analyzer/app.pyservices/ingest/README.mdservices/ingest/app.py
![cubic-dev-ai[bot]](https://avatars.githubusercontent.com/in/1082092?s=60&v=4){kind=small}
There was a problem hiding this comment.
1 issue found and verified against the latest diff
Reply with feedback, questions, or to request a fix.
Re-trigger cubic
There was a problem hiding this comment.
🧹 Nitpick comments (2)
services/ingest/app.py (1)
150-155: 💤 Low valueHeader name casing differs from analyzer service.
The analyzer service defines the header as
x-api-key(lowercase) while this service usesX-API-Key(mixed case). Although HTTP headers are case-insensitive at runtime, the OpenAPI documentation will display different header names, potentially confusing API consumers.Consider aligning with the analyzer service for consistency:
Suggested change
api_key_scheme = APIKeyHeader( - name="X-API-Key", + name="x-api-key", description="Enter your TENET AI API key to authenticate requests.", auto_error=False )🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@services/ingest/app.py` around lines 150 - 155, The APIKeyHeader instantiation for api_key_scheme uses mixed case header name X-API-Key, but the analyzer service uses lowercase x-api-key for the same purpose. Change the name parameter in the APIKeyHeader constructor from "X-API-Key" to "x-api-key" to align with the analyzer service and ensure consistent OpenAPI documentation across services..github/workflows/publish-doc.yml (1)
93-102: ⚡ Quick winConsider pinning actions to commit SHAs for supply chain security.
The static analysis tool flags that actions are pinned to version tags rather than commit hashes. While version tags are common for first-party GitHub actions, pinning to SHAs provides stronger supply chain security by preventing tag-mutation attacks.
Example for
actions/configure-pages:# Instead of: uses: actions/configure-pages@v6.0.0 # Use: uses: actions/configure-pages@<commit-sha> # v6.0.0This applies to
configure-pages,upload-pages-artifact, anddeploy-pages.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In @.github/workflows/publish-doc.yml around lines 93 - 102, Replace the version tag references for the three GitHub Actions with their corresponding commit SHAs to improve supply chain security. For actions/configure-pages, actions/upload-pages-artifact, and actions/deploy-pages, change each occurrence from the format `@v`<version> (such as `@v6.0.0` or `@v5.0.0`) to the format @<commit-sha>, optionally including the version tag as a comment after the SHA for reference.Source: Linters/SAST tools
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Nitpick comments:
In @.github/workflows/publish-doc.yml:
- Around line 93-102: Replace the version tag references for the three GitHub
Actions with their corresponding commit SHAs to improve supply chain security.
For actions/configure-pages, actions/upload-pages-artifact, and
actions/deploy-pages, change each occurrence from the format `@v`<version> (such
as `@v6.0.0` or `@v5.0.0`) to the format @<commit-sha>, optionally including the
version tag as a comment after the SHA for reference.
In `@services/ingest/app.py`:
- Around line 150-155: The APIKeyHeader instantiation for api_key_scheme uses
mixed case header name X-API-Key, but the analyzer service uses lowercase
x-api-key for the same purpose. Change the name parameter in the APIKeyHeader
constructor from "X-API-Key" to "x-api-key" to align with the analyzer service
and ensure consistent OpenAPI documentation across services.
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro Plus
Run ID: 78d1c154-4a02-4c7e-83b7-0d3ba42250ca
📒 Files selected for processing (2)
.github/workflows/publish-doc.ymlservices/ingest/app.py
|
@S3DFX-CYBER Review |
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
|
@coderabbitai why is so many prs having CI test failure |
|
Tip For best results, initiate chat on the files or code changes. 🧩 Analysis chain🏁 Script executed: #!/bin/bash
set -euo pipefail
echo "== PR `#176` check status =="
gh pr view 176 --repo TENET-DEV-AI/TENET-AI --json number,title,headRefName,baseRefName,statusCheckRollup \
| jq '{
number,
title,
headRefName,
baseRefName,
checks: [.statusCheckRollup[] | {
name: (.name // .context // "unknown"),
status: .status,
conclusion: .conclusion,
detailsUrl: (.detailsUrl // "")
}]
}'
echo
echo "== Recent PRs and their mergeability/status =="
gh pr list --repo TENET-DEV-AI/TENET-AI --limit 15 --state all \
--json number,title,state,mergeStateStatus,headRefName,baseRefName,updatedAt \
| jq '.[] | {number,title,state,mergeStateStatus,headRefName,baseRefName,updatedAt}'
echo
echo "== Recent workflow runs (last 20) =="
gh run list --repo TENET-DEV-AI/TENET-AI --limit 20 --json databaseId,workflowName,displayTitle,event,status,conclusion,headBranch,createdAt,updatedAt,url \
| jq '.[] | {databaseId,workflowName,displayTitle,event,status,conclusion,headBranch,createdAt,updatedAt,url}'
echo
echo "== Workflow files in repo =="
fd .github/workflows -t f . || true
echo
echo "== Outline of workflow files =="
fd -t f .github/workflows | while read -r f; do
echo "-- $f"
sed -n '1,220p' "$f"
echo
doneLength of output: 17493 🏁 Script executed: #!/bin/bash
set -euo pipefail
echo "== Workflow files =="
fd . .github/workflows -t f
echo
for f in $(fd . .github/workflows -t f | sort); do
echo "===== FILE: $f ====="
sed -n '1,240p' "$f"
echo
done
echo
echo "== CI run `#28327889584` jobs =="
gh run view 28327889584 --repo TENET-DEV-AI/TENET-AI --json jobs \
| jq '.jobs[] | {name, conclusion, startedAt, completedAt, steps: [.steps[] | {name, conclusion, number}]}'
echo
echo "== CI run `#28327889584` failed log =="
gh run view 28327889584 --repo TENET-DEV-AI/TENET-AI --log-failed || true
echo
echo "== CI run `#28327809439` jobs =="
gh run view 28327809439 --repo TENET-DEV-AI/TENET-AI --json jobs \
| jq '.jobs[] | {name, conclusion, startedAt, completedAt, steps: [.steps[] | {name, conclusion, number}]}'
echo
echo "== CI run `#28327809439` failed log =="
gh run view 28327809439 --repo TENET-DEV-AI/TENET-AI --log-failed || true
echo
echo "== TENET Agent PR Review run `#28327889589` jobs =="
gh run view 28327889589 --repo TENET-DEV-AI/TENET-AI --json jobs \
| jq '.jobs[] | {name, conclusion, startedAt, completedAt, steps: [.steps[] | {name, conclusion, number}]}'
echo
echo "== TENET Agent PR Review run `#28327889589` failed log =="
gh run view 28327889589 --repo TENET-DEV-AI/TENET-AI --log-failed || trueLength of output: 52554
What’s happening:
Exact failure:
Second failure source:
So the short answer is:
If you want, I can help identify the smallest fix for both workflows. (/)_(\ /) |
Summary
Key Changes
x-api-keyheader.main.Related Issue
Fixes #98
Type of Change
Screenshots / Logs (Optional)
How Has This Been Tested?
Checklist
Additional Notes (Optional)
Summary by cubic
Generates and publishes OpenAPI docs for the Ingest and Analyzer services on every push to
main. Adds Swagger UI/ReDoc with API key auth, standardized errors, endpoint tags, and a landing page with live Petstore links.New Features
fastapi.security.APIKeyHeader+Security(X-API-Keyfor Ingest,x-api-keyfor Analyzer).ErrorResponseand documented common errors (401/403/404/422/429/503)..github/workflows/publish-doc.ymlimports FastAPI apps to export schemas, sets mockREDIS_HOSTfor init, builds a landing page with dynamic Petstore links, uploads viaactions/upload-pages-artifact, configures withactions/configure-pages, deploys withactions/deploy-pages; READMEs document local/docs,/redoc, and schema URLs with Swagger auth steps.Bug Fixes
Written for commit 1daa4c3. Summary will update on new commits.
Summary by CodeRabbit
mainupdates.