feat: improve API documentation and OpenAPI specification

[Arpita2919]

Summary

This PR improves the project's API documentation by auditing the existing implementation and updating the documentation to accurately reflect the current API. It enhances both the OpenAPI specification and the developer-facing documentation with request/response schemas, authentication details, error handling, and usage examples.

Closes #2871

---

Type of Change

• 🐛 Bug fix (non-breaking change that fixes an issue)
• ✨ New feature (non-breaking change that adds functionality)
• 💥 Breaking change (fix or feature that changes existing behavior)
• 📝 Documentation update
• ♻️ Refactor / code cleanup (no functional change)
• ⚡ Performance improvement
• 🔒 Security fix
• 🧪 Tests only

---

What Changed

• Updated api.md to provide accurate and comprehensive API documentation.
• Improved openapi.yaml to match the current API implementation with complete endpoint definitions.
• Added request/response schemas, authentication requirements, error responses, and example requests in JavaScript, Python, and cURL where applicable.
• Documented API endpoints under src/app/api/metrics/, src/app/api/goals/, src/app/api/user/, and other public API routes as needed.
• Enhanced documentation consistency and ensured compatibility with Swagger UI.

---

How to Test

1. Open the updated api.md and verify that all documented endpoints match the current implementation.
2. Validate the openapi.yaml specification using Swagger Editor or the project's /api-docs endpoint.
3. Confirm that request/response examples, authentication details, and error codes are accurate.

Expected result:

• All API endpoints are documented correctly.
• Swagger/OpenAPI specification validates successfully.
• Documentation accurately reflects the current implementation.

---

Screenshots / Recordings

Not applicable (Documentation-only changes).

---

Checklist

• Linked the related issue above
• Self-reviewed my own diff
• No unnecessary console.log, debug code, or commented-out blocks
• npm run lint passes locally (not applicable for documentation-only changes if lint is not configured for docs)
• No TypeScript errors (npm run type-check) (not applicable if no source code was modified)
• Added or updated tests where applicable (not applicable)
• Updated documentation / comments if behavior changed

---

Accessibility (UI changes only)

Not applicable.

---

Additional Context

This PR contains documentation-only changes and does not modify application logic, API behavior, or runtime functionality. The goal is to improve developer experience by providing complete and accurate API documentation that stays aligned with the current implementation.

[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

[Arpita2919]

Hey @Priyanshu-byte-coder, please review and merge it.

[Arpita2919]

Hi @maintainers,

I've addressed the requested issue and completed the implementation. The changes are documentation-only and include comprehensive updates to the API documentation to better reflect the current implementation. I have also reviewed the changes to ensure they are consistent with the existing project structure.

All relevant checks have passed on my side, and the PR is ready for review.

When you have time, could you please review and merge this PR if everything looks good? If any changes are required, I'd be happy to make them.

Thank you for your time and feedback!