Skip to content

Add missing OpenAPI endpoint documentation#204

Merged
Vedant1515 merged 1 commit intomasterfrom
docs/openapi-documentation
Apr 2, 2026
Merged

Add missing OpenAPI endpoint documentation#204
Vedant1515 merged 1 commit intomasterfrom
docs/openapi-documentation

Conversation

@vicheachin1688
Copy link
Copy Markdown
Collaborator

@vicheachin1688 vicheachin1688 commented Mar 31, 2026

Key Changes:
Security Implementation: Added BearerAuth to components/securitySchemes to support JWT-protected routes.
New Endpoints Documented:
POST /api/login: User authentication and JWT generation.
POST /api/signup: New user registration.
GET /api/auth/profile: Authenticated user profile retrieval.
Schema Updates: Added LoginRequest, SignupRequest, and UserProfileResponse components.
Cleanup: Identified and prepared for the removal of "ghost" routes that exist in documentation but not in the routes/ directory.

@TienNguyen3711
Copy link
Copy Markdown
Collaborator

TienNguyen3711 commented Apr 2, 2026

Hi, Vichea
Thank you for doing it. Here are a few areas that still need adjustment before this branch can be considered complete:

  1. GET /appointments is still active but not documented.
    The backend currently exposes both GET /appointments and GET /appointments/v2, so documenting only the V2 endpoint is not enough. If the legacy endpoint is still part of the live API surface, it should either be documented or removed from the backend to avoid ambiguity.

  2. POST /login documentation does not fully match actual backend behavior.
    The current spec documents standard success and error responses, but the controller can also return additional cases such as:

  • 202 Accepted when MFA is enabled and a token is sent
  • 404 Not Found when the account does not exist
  • 429 Too Many Requests when failed login attempts exceed the allowed threshold
    These responses should be added so frontend and mobile clients can handle the authentication flow correctly.
  1. The notification routes are not fully aligned with the documented path parameters.
    The backend uses /:id for update and delete operations, while the spec documents /notifications/{simple_id}. Even if both refer to the same underlying value, the naming should be made consistent between routes, validators, controllers, and OpenAPI docs.

  2. Some request and response schemas are too generic compared to the real controller output.
    A number of endpoints still use minimal schema definitions or high-level descriptions instead of matching the actual JSON response shape. This makes the spec less reliable for consumers who want to generate clients or trust the docs without reading controller code.

  3. Authentication requirements need one more consistency pass.
    Several protected endpoints are correctly marked with bearer authentication, but the documentation should be rechecked route-by-route to ensure every protected endpoint is explicitly marked and every public endpoint is left unprotected intentionally.

Please review and fix it

@Vedant1515 Vedant1515 merged commit b2d2fba into master Apr 2, 2026
8 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants