docs(api): add API documentation guide

[pari-28]

Summary

Added a dedicated API documentation guide and improved discoverability of existing API resources.

Closes #1079

---

Type of Change

• Bug fix
• New feature
• Documentation update
• Refactor / code cleanup

---

Changes Made

• Added docs/api.md as a human-readable API documentation guide
• Added an API Documentation section to README.md
• Documented authentication requirements and major API categories
• Added references to the existing OpenAPI specification (public/openapi.yaml)
• Documented usage of the interactive Swagger UI (/api-docs)
• Added contributor guidance for keeping API documentation synchronized with API changes

---

How to Test

1. Open docs/api.md and verify all sections render correctly
2. Open README.md and verify the API Documentation section appears correctly
3. Run the application locally
4. Navigate to http://localhost:3000/api-docs
5. Verify Swagger UI loads successfully and references the OpenAPI specification

---

Screenshots (if UI change)

N/A

---

Checklist

• Linked issue in summary
• Documentation reviewed for accuracy
• Self-reviewed the changes
• Added new documentation where appropriate
• Added/updated tests if applicable

---

Additional Notes

While auditing the repository, I found that the current API implementation differs from several endpoints listed in the original issue description. This PR documents the current API structure and complements the existing OpenAPI specification and Swagger UI rather than duplicating them.

[vercel]

@pari-28 is attempting to deploy a commit to the PRIYANSHU DOSHI's projects Team on Vercel.

A member of the Team first needs to authorize it.

[github-actions]

Thanks for your first PR on DevTrack! 🎉

A maintainer will review it within 48 hours. While you wait:

• Make sure CI is passing (type-check + lint)
• Double-check the PR description is filled out and the issue is linked
• Feel free to ask questions in Discussions if you need help

If you find DevTrack useful, a ⭐ star on the repo is always appreciated — it helps the project grow and attract more contributors!

[github-actions]

GSSoC Label Checklist 🏷️

@Priyanshu-byte-coder — please apply the appropriate labels before merging:

Difficulty (pick one):

• level:beginner — 20 pts
• level:intermediate — 35 pts
• level:advanced — 55 pts
• level:critical — 80 pts

Quality (optional):

• quality:clean — ×1.2 multiplier
• quality:exceptional — ×1.5 multiplier

Validation (required to score):

• gssoc:approved — counts for points
• gssoc:invalid / gssoc:spam / gssoc:ai-slop — does not score

Type labels (type:*) are auto-detected from files and title. Review and adjust if needed.
Points formula: (difficulty × quality_multiplier) + type_bonus

[pari-28]

Hi @Priyanshu-byte-coder ,

While implementing #1079, I audited the current API surface to ensure the documentation matched the repository's actual implementation.

Findings during the audit

• /api/user/settings currently exposes GET and PATCH methods rather than GET and POST as described in the issue.
• /api/notifications currently exposes GET and PATCH methods. I could not find a separate /api/notifications/read endpoint in the current codebase.
• Metrics functionality is implemented across many routes under /api/metrics/* rather than a single /api/metrics endpoint.
• The repository already contains a comprehensive OpenAPI specification at public/openapi.yaml (~500+ lines).
• The project already includes an interactive Swagger UI available at /api-docs.
• I could not find a route matching /api/github/sync in the current implementation.
• The current API surface contains significantly more endpoints than those listed in the original issue description.

Approach taken in this PR

To avoid duplicating existing documentation and creating multiple sources of truth, this PR:

• Adds docs/api.md as a human-readable API guide.
• Documents authentication requirements and major API categories.
• Documents how to access the existing Swagger UI (/api-docs).
• References the existing OpenAPI specification (public/openapi.yaml).
• Adds contributor guidance for keeping API documentation synchronized with API changes.
• Adds README references to the available API documentation resources.

This documentation reflects the current implementation found under src/app/api and is intended to complement the existing OpenAPI specification rather than replace or duplicate it.

If you'd prefer additional endpoint-level documentation or a different scope, I'd be happy to update the PR accordingly.

Thank you!

[github-actions]

🎉 Merged! Thanks for contributing to DevTrack.

If the project has been useful to you, a ⭐ star on the repo is the easiest way to support it — it helps DevTrack get discovered by more developers.

Keep an eye on open issues for your next contribution!