feat(api): add OpenAPI documentation with security schemes#4896
Closed
vietlinhh02 wants to merge 1 commit into
Closed
feat(api): add OpenAPI documentation with security schemes#4896vietlinhh02 wants to merge 1 commit into
vietlinhh02 wants to merge 1 commit into
Conversation
Improves API documentation: - JWT Bearer and API Key security schemes in OpenAPI spec - Global security requirements for all endpoints - Example values for all response models - Error response schemas (400, 401, 403, 404, 429) - Endpoint summaries and descriptions - Swagger UI and ReDoc available at /docs and /redoc - 11 passing tests Closes ClankerNation#185
There was a problem hiding this comment.
Pull request overview
Note
Copilot was unable to run its full agentic suite in this review.
Adds richer OpenAPI documentation (auth schemes, standardized error responses, examples/summaries) and introduces tests that assert the generated OpenAPI schema contains these elements.
Changes:
- Added OpenAPI schema tests validating security schemes, error response schemas, examples, and docs endpoints.
- Enhanced FastAPI app metadata and endpoint docs (tags/summaries/descriptions) and added response models/examples.
- Implemented a custom OpenAPI generator to inject global security schemes and default error responses.
Reviewed changes
Copilot reviewed 2 out of 6 changed files in this pull request and generated 3 comments.
| File | Description |
|---|---|
| api/tests/test_openapi.py | Adds tests to validate OpenAPI schema contents and docs endpoints availability. |
| api/main.py | Expands OpenAPI metadata/models and injects security + error responses via custom_openapi(). |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Comment on lines
+274
to
+287
| openapi_schema["components"]["securitySchemes"] = { | ||
| "BearerAuth": { | ||
| "type": "http", | ||
| "scheme": "bearer", | ||
| "bearerFormat": "JWT", | ||
| "description": "JWT token obtained from the login endpoint", | ||
| }, | ||
| "ApiKeyAuth": { | ||
| "type": "apiKey", | ||
| "in": "header", | ||
| "name": "X-API-Key", | ||
| "description": "API key for programmatic access", | ||
| }, | ||
| } |
Comment on lines
+291
to
+297
| error_responses = { | ||
| "400": {"description": "Bad request", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorResponse"}}}}, | ||
| "401": {"description": "Authentication required", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorResponse"}}}}, | ||
| "403": {"description": "Forbidden", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorResponse"}}}}, | ||
| "404": {"description": "Not found", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorResponse"}}}}, | ||
| "429": {"description": "Rate limited", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorResponse"}}}}, | ||
| } |
Comment on lines
+4
to
+7
| import sys | ||
| import os | ||
|
|
||
| sys.path.insert(0, os.path.join(os.path.dirname(__file__), "..", "..")) |
|
Unfortunately the changes in this PR didn't fully resolve the issue. Please rework your solution and submit a new pull request within 2 hours. Make sure to review the acceptance criteria in the linked issue and verify all conditions are met before resubmitting. |
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 free
to 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
Implements OpenAPI documentation improvements as requested in #185.
Changes
api/main.py— Enhanced OpenAPI schema:BearerAuth(JWT) andApiKeyAuth(API key)openapi()function to generate complete schemaapi/routes/agents.py— Added summaries to all endpointsapi/tests/test_openapi.py— 11 tests:Acceptance Criteria
Closes #185