Improve OpenAPI, introduce Bruno collection#586
Open
byewokko wants to merge 2 commits into
Open
Conversation
📝 WalkthroughWalkthroughThis PR adds a new Bruno API request collection under docs/bruno covering Clients, OAuth 2.0/OIDC, Passwords, Roles, Sessions, and Tenants endpoints, plus collection config and environment variables. It also expands OpenAPI-style docstrings in client, credentials, session, and tenant handlers without changing handler logic. ChangesBruno API collection
Handler docstring documentation
Estimated code review effort: 2 (Simple) | ~15 minutes Suggested labels: documentation Suggested reviewers: none 🐰 A rabbit hopped through docs anew, 🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches📝 Generate docstrings
🧪 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: 2
🤖 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 `@seacatauth/client/handler.py`:
- Around line 164-170: The register_client response documentation is missing the
404 branch for unknown providers, so update the response table to include the
provider-not-found case alongside the existing 200/400/403 entries. Use the
register_client handler and its provider lookup path as the reference point, and
make sure the documented status codes match the actual return values.
In `@seacatauth/credentials/handler.py`:
- Around line 410-436: Document the alternate `password_reset` response shape in
the credentials creation endpoint docs, since `handler.py` can return a 200 with
a `password_reset` error payload when `passwordlink` is enabled. Update the
response example and description near the existing create-credentials response
block to mention this envelope alongside the happy path, so clients know to
handle both outcomes from the same endpoint.
🪄 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
Run ID: 60f99263-946e-4756-9ae7-e3ea9b860f25
📒 Files selected for processing (29)
docs/bruno/Clients/Delete client.brudocs/bruno/Clients/Get client.brudocs/bruno/Clients/List clients.brudocs/bruno/Clients/Register client.brudocs/bruno/Clients/Update client.brudocs/bruno/Clients/folder.brudocs/bruno/OAuth 2.0 OpenID Connect/OIDC Discovery.brudocs/bruno/OAuth 2.0 OpenID Connect/Token request.brudocs/bruno/OAuth 2.0 OpenID Connect/folder.brudocs/bruno/Passwords/Password policy.brudocs/bruno/Passwords/folder.brudocs/bruno/Roles/Create role.brudocs/bruno/Roles/List tenant roles.brudocs/bruno/Roles/folder.brudocs/bruno/Sessions/List sessions.brudocs/bruno/Sessions/folder.brudocs/bruno/Tenants/Create tenant.brudocs/bruno/Tenants/Delete tenant.brudocs/bruno/Tenants/Get tenant.brudocs/bruno/Tenants/List tenants.brudocs/bruno/Tenants/Search tenants.brudocs/bruno/Tenants/Update tenant.brudocs/bruno/Tenants/folder.brudocs/bruno/bruno.jsondocs/bruno/environments/localhost.bruseacatauth/client/handler.pyseacatauth/credentials/handler.pyseacatauth/session/handler.pyseacatauth/tenant/handler.py
Comment on lines
+164
to
+170
| responses: | ||
| 200: | ||
| description: Client registered successfully | ||
| 400: | ||
| description: Invalid client metadata | ||
| 403: | ||
| description: Insufficient permissions to register client |
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win
Document the 404 provider-not-found response.
register_client already returns 404 when the provider lookup fails, so the response table should include that branch; otherwise the contract is incomplete for unknown providers.
💡 Suggested doc update
responses:
description: Client registered successfully
description: Invalid client metadata
description: Insufficient permissions to register client
+ 404:
+ description: Provider not found📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| responses: | |
| 200: | |
| description: Client registered successfully | |
| 400: | |
| description: Invalid client metadata | |
| 403: | |
| description: Insufficient permissions to register client | |
| responses: | |
| 200: | |
| description: Client registered successfully | |
| 400: | |
| description: Invalid client metadata | |
| 403: | |
| description: Insufficient permissions to register client | |
| 404: | |
| description: Provider not found |
🤖 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 `@seacatauth/client/handler.py` around lines 164 - 170, The register_client
response documentation is missing the 404 branch for unknown providers, so
update the response table to include the provider-not-found case alongside the
existing 200/400/403 entries. Use the register_client handler and its provider
lookup path as the reference point, and make sure the documented status codes
match the actual return values.
Comment on lines
+410
to
+436
| Example response: | ||
| ```json | ||
| { | ||
| "result": "OK", | ||
| "status": "OK", | ||
| "_id": "mongodb:default:abc123def456", | ||
| "_type": "mongodb", | ||
| "_provider_id": "mongodb:default" | ||
| } | ||
| ``` | ||
| --- | ||
| parameters: | ||
| - name: provider | ||
| in: path | ||
| description: ID of the credential provider to create the credentials in | ||
| required: true | ||
| schema: | ||
| type: string | ||
| responses: | ||
| 200: | ||
| description: Credentials created successfully | ||
| 400: | ||
| description: Invalid request data or credentials already exist | ||
| 403: | ||
| description: Insufficient permissions to create credentials | ||
| 404: | ||
| description: Provider not found |
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win
Document the password_reset response envelope.
This endpoint can return password_reset with an error payload while still responding 200. The current doc only shows the happy path, so clients won't know to handle the reset-link failure case.
💡 Suggested doc update
Example response:
```json
{
"result": "OK",
"status": "OK",
"_id": "mongodb:default:abc123def456",
"_type": "mongodb",
"_provider_id": "mongodb:default"
}
```
+ When `passwordlink` is enabled, the response may also include a `password_reset`
+ object with either success details or an error payload.📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| Example response: | |
| ```json | |
| { | |
| "result": "OK", | |
| "status": "OK", | |
| "_id": "mongodb:default:abc123def456", | |
| "_type": "mongodb", | |
| "_provider_id": "mongodb:default" | |
| } | |
| ``` | |
| --- | |
| parameters: | |
| - name: provider | |
| in: path | |
| description: ID of the credential provider to create the credentials in | |
| required: true | |
| schema: | |
| type: string | |
| responses: | |
| 200: | |
| description: Credentials created successfully | |
| 400: | |
| description: Invalid request data or credentials already exist | |
| 403: | |
| description: Insufficient permissions to create credentials | |
| 404: | |
| description: Provider not found | |
| Example response: |
🤖 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 `@seacatauth/credentials/handler.py` around lines 410 - 436, Document the
alternate `password_reset` response shape in the credentials creation endpoint
docs, since `handler.py` can return a 200 with a `password_reset` error payload
when `passwordlink` is enabled. Update the response example and description near
the existing create-credentials response block to mention this envelope
alongside the happy path, so clients know to handle both outcomes from the same
endpoint.
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
1 participant
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 by CodeRabbit