Docs: Align API documentation with implementation #27
Conversation
Updated service documentation in the docs/ folder (auth, expense, group, user) to accurately reflect the implemented API endpoints, request/response schemas, and current feature status. - Ensured all existing API routes are documented. - Marked features that are present in documentation but not fully implemented in the backend with TODO notes (e.g., expense attachment download, settlement checks on group leave, specific fields in create expense response). - Corrected field names in example responses to match Pydantic schemas (e.g., snake_case vs camelCase).
✅ Deploy Preview for splitwizer canceled.
|
WalkthroughThe documentation for four service APIs—authentication, expense, group, and user—was updated. Additions include new endpoint descriptions, expanded request/response examples, clarifications on current and planned behaviors, and standardization of field naming conventions. No underlying code or API signatures were changed; all modifications are documentation-only. Changes
Sequence Diagram(s)sequenceDiagram
participant Client
participant AuthService
Client->>AuthService: POST /auth/token (username, password)
AuthService-->>Client: { "access_token": "..." }
sequenceDiagram
participant Client
participant GroupService
Client->>GroupService: GET /groups/{group_id}/members
GroupService-->>Client: [ { userId, role, joinedAt, name, profileImageUrl }, ... ]
Poem
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. 🪧 TipsChatThere are 3 ways to chat with CodeRabbit:
SupportNeed help? Create a ticket on our support page for assistance with any issues or questions. Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments. CodeRabbit Commands (Invoked using PR comments)
Other keywords and placeholders
CodeRabbit Configuration File (
|
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## main #27 +/- ##
=======================================
Coverage 84.09% 84.09%
=======================================
Files 27 27
Lines 3176 3176
=======================================
Hits 2671 2671
Misses 505 505
🚀 New features to boost your workflow:
|
![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
🧹 Nitpick comments (8)
docs/user-service.md (1)
92-99: Inconsistent naming between request & response may confuse integratorsThe response now uses
image_url,created_at,updated_at, etc., yet the request example above (lines 78-84, unchanged) still showsimageUrl(camelCase). Unless the API intentionally accepts camelCase input while returning snake_case output, consider updating the request example or adding an explicit note so clients don’t guess.docs/expense-service.md (3)
122-125: Key names use camelCase while the rest of the doc drifts to snake_case
"settlements"is fine, but"groupSummary"re-introduces camelCase right after the user-service doc standardised on snake_case (group_summary?). Decide on one style across services for less friction in client SDKs.
127-165: Good transparency about TODO fields – add explicit status code for clarityYou flag the placeholders and provide the intended structure – nice. Consider adding a short code sample of the current 200 OK with
"groupSummary": nulland a future 200 example, or move the long “intended” example behind a collapsible<details>tag to keep the main flow compact.
317-318: Provide concrete 501 exampleSince you explicitly state the endpoint returns
501 Not Implemented, a small snippet like501 Not Implemented { "error": "Attachment download not yet implemented" }would set expectations.
docs/group-service.md (2)
177-178: Clarify current vs. future behaviour in bold or call-out boxStating that the balance check is TODO is fine, but highlighting it (e.g.,
> **⚠️ Current limitation:** …) will prevent consumers from assuming enforced logic.
201-236: Great addition – consider envelope pattern for consistencyEvery other list endpoint (
/expenses,/settlements, etc.) wraps results in an object with metadata ({ items: [...], pagination: {...} }). Returning a bare array here deviates from that pattern; if this is intentional, add a note.docs/auth-service.md (2)
14-15: Row formatting inconsistent with earlier entriesFor
/auth/token, wrap the path in back-ticks and add an anchor like the other rows for uniform rendering & clickable navigation.-| POST | `/auth/token` | OAuth2 compatible token login (for Swagger UI/OpenAPI) | +| POST | [`/auth/token`](#6-oauth2-token-endpoint-primarily-for-swaggeropenapi) | OAuth2 compatible token login (for Swagger UI/OpenAPI) |
241-245: Missing fenced-block language triggers MD040Specify a language (
textworks) to silence markdown-lint and improve syntax highlighting.-``` +```text [email protected] password=userpassword</blockquote></details> </blockquote></details> <details> <summary>📜 Review details</summary> **Configuration used: CodeRabbit UI** **Review profile: CHILL** **Plan: Pro** <details> <summary>📥 Commits</summary> Reviewing files that changed from the base of the PR and between 46f0987708c90e5702c5d24c99e80f98e974a108 and ee8dcddf764b3fa044e162796b8a7fdc65281662. </details> <details> <summary>📒 Files selected for processing (4)</summary> * `docs/auth-service.md` (2 hunks) * `docs/expense-service.md` (4 hunks) * `docs/group-service.md` (2 hunks) * `docs/user-service.md` (2 hunks) </details> <details> <summary>🧰 Additional context used</summary> <details> <summary>🪛 markdownlint-cli2 (0.17.2)</summary> <details> <summary>docs/auth-service.md</summary> 242-242: Fenced code blocks should have a language specified null (MD040, fenced-code-language) </details> </details> <details> <summary>🪛 LanguageTool</summary> <details> <summary>docs/group-service.md</summary> [uncategorized] ~232-~232: Loose punctuation mark. Context: ...nique identifier of the member. - `role`: The role of the member in the group (e.... (UNLIKELY_OPENING_PUNCTUATION) --- [uncategorized] ~233-~233: Loose punctuation mark. Context: ... (e.g., "admin", "member"). - `joinedAt`: The timestamp when the member joined th... (UNLIKELY_OPENING_PUNCTUATION) --- [uncategorized] ~234-~234: Loose punctuation mark. Context: ...en the member joined the group. - `name`: The name of the user (fetched from user... (UNLIKELY_OPENING_PUNCTUATION) --- [uncategorized] ~235-~235: Loose punctuation mark. Context: ...fetched from user profile). - `imageUrl`: The profile image URL of the user (fetc... (UNLIKELY_OPENING_PUNCTUATION) </details> </details> </details> <details> <summary>🔇 Additional comments (3)</summary><blockquote> <details> <summary>docs/user-service.md (1)</summary> `42-43`: **Field rename looks good – matches Pydantic output** `updated_at` now follows the snake_case convention introduced elsewhere in the docs & backend models. 👍 </details> <details> <summary>docs/expense-service.md (1)</summary> `304-305`: **Attachment upload section: flag missing persistence earlier** The note is helpful; you might also mention that a 201 is returned even though storage is simulated, so API testers don’t misinterpret the behaviour. </details> <details> <summary>docs/auth-service.md (1)</summary> `190-256`: **Comprehensive section – nice!** The expanded password-reset and OAuth2 docs align well with the rest of the spec. </details> </blockquote></details> </details> <!-- This is an auto-generated comment by CodeRabbit for review status -->
|
|
||
| --- | ||
|
|
There was a problem hiding this comment.
Anchor in summary table is now stale
Row 15 in the summary table still links to #4-crud-endpoints-recap even though the dedicated section is now §5 List Group Members. Update the link target to keep in-page navigation working.
-| GET | [`/groups/{group_id}/members`](#4-crud-endpoints-recap) | List members |
+| GET | [`/groups/{group_id}/members`](#5-list-group-members) | List members |Committable suggestion skipped: line range outside the PR's diff.
🤖 Prompt for AI Agents
In docs/group-service.md around lines 198 to 200, the anchor link in row 15 of
the summary table incorrectly points to #4-crud-endpoints-recap instead of the
updated section §5 List Group Members. Update the href attribute of the anchor
tag in that row to #5-list-group-members to ensure the in-page navigation link
is correct and functional.
Updated service documentation in the docs/ folder (auth, expense, group, user) to accurately reflect the implemented API endpoints, request/response schemas, and current feature status.
Summary by CodeRabbit