feat: implement Swagger/OpenAPI documentation (#52) (Apertre3.0)

[Aditya-18849]

PR Description: Implement Interactive API Documentation with Swagger/OpenAPI (#52)
📝 Overview
This PR introduces centralized, interactive API documentation for the RIVETO backend using Swagger UI and OpenAPI 3.0.0. This solves the issue of frontend developers having to manually parse backend code to understand endpoint structures, headers, and payloads.

🛠️ Key Changes
Swagger Integration: Installed and configured swagger-ui-express and swagger-jsdoc within the backend service.

Centralized Configuration: Pivoted to a dedicated Swagger.js configuration file to define paths and schemas. This avoids YAML indentation conflicts with the project's Prettier/ESLint settings while keeping route files clean.

Initial Documentation Scope (Auth Routes): Fully documented the following endpoints:

POST /api/auth/registration (Includes user schema)

POST /api/auth/login (Includes example credentials)

GET /api/auth/logout

POST /api/auth/googlelogin (OAuth token handling)

POST /api/auth/adminlogin (Admin-specific access)

Schema Definitions: Added reusable components for Error responses and Bearer Auth (JWT) security schemes.

![Uploading image.png…]()

[Aditya-18849]

@akshay0611 , please check this pr , and verify it

[akshay0611]

Good progress on the Swagger implementation, @Aditya-18849 I appreciate how you communicated your approach and pivoted when you hit the Prettier conflict. However, there are some critical issues to address:

Critical Issues (MUST FIX):

1. Node modules committed - backend/node_modules should never be in Git (I can see +159, -652,163 lines in the file changes). Remove with:

   git rm -r --cached backend/node_modules
   git commit -m "Remove node_modules from repository"

Verify node_modules/ is in your .gitignore

2. Missing import - cookieParser is used but not imported. Add to index.js:

   import cookieParser from 'cookie-parser';

About the JSDoc vs Config File Approach:

You made a reasonable decision to avoid the Prettier conflict, but using a separate config file creates the exact maintainability problem I mentioned - docs can drift from actual code when routes change.

Consider this hybrid approach:

// In Swagger.js
const options = {
  definition: { /* your OpenAPI spec */ },
  apis: ['./routes/*.js'], // Auto-discover from route files
};

Then add simple JSDoc comments in route files:

/**
 * @swagger
 * /api/auth/login:
 *   post:
 *     summary: Log in a user
 */
router.post('/login', loginController);

This keeps documentation next to the actual routes (easier to maintain when routes change) while keeping your clean Swagger.js for reusable schemas and components.

Also Consider:

• Document all API endpoints (you have orderRoutes imported but not documented)
• Apply the bearerAuth security scheme you defined to protected endpoints
• Add response body schemas (not just descriptions)

Fix the critical issues first (especially removing node_modules), then let's discuss the documentation approach

[Aditya-18849]

hi @akshay0611 Removed node_modules: Cleared the massive folder from Git's tracking and verified that node_modules/ is strictly enforced in the .gitignore.

Added Missing Import: Added import cookieParser from 'cookie-parser'; to the top of backend/index.js.

Merge Conflict Resolved: I noticed backend/package-lock.json was deleted upstream in main, so I accepted that deletion on my branch to clear the merge conflict and keep everything perfectly synced and i am up for the documentation approach as you have mentioned, kindly check the updated PR and verify the changes made

[akshay0611]

Good work on creating comprehensive documentation for all 5 Auth routes, @Aditya-18849 The Swagger.js file has detailed schemas, examples, and error responses - that's excellent.

However, there's a critical issue: the route files have zero documentation or connection to Swagger.

The problem:
When I open authRoutes.js, I see:

authRoutes.post("/registration", registration);
authRoutes.post("/login", login);
// etc... no indication these are documented

If a developer modifies these routes in the future, they won't know Swagger documentation exists or needs updating. This defeats the whole purpose of API documentation - keeping it synchronized with the code.

What's needed:
At minimum, add JSDoc comments in the route files that reference or define the endpoints:

/**
 * @swagger
 * /api/auth/registration:
 *   post:
 *     summary: Register a new user
 *     tags: [Auth]
 *     requestBody:
 *       required: true
 *       content:
 *         application/json:
 *           schema:
 *             type: object
 *             required: [name, email, password]
 *             properties:
 *               name: {type: string, example: "John Doe"}
 *               email: {type: string, example: "john@example.com"}
 *               password: {type: string, example: "StrongPass123!"}
 *     responses:
 *       201:
 *         description: User registered successfully
 */
authRoutes.post("/registration", registration);

Then update Swagger.js:

apis: ['./routes/*.js'] // Enable auto-discovery

Why this matters:

• Developers see docs when they look at routes
• Docs stay synchronized with code changes
• This is the industry-standard Swagger pattern

The documentation you created is great - it just needs to be connected to the actual route definitions. Let me know if you need help with the JSDoc syntax!

[Aditya-18849]

Hi @akshay0611 , as you have requested the changes , here are the things that are implemented:
--- Implemented hybrid swagger.js docs with inline JSDoc

The updated PR is ready for review with no merge conflicts

[akshay0611]

Thanks for the update, @Aditya-18849! You've made solid progress - removing node_modules and setting up the initial JSDoc structure is a good step forward.

However, there are a few technical issues we need to address before this is ready for main:

---

1. Indentation is Critical (JSDoc / YAML)

In authRoutes.js, the JSDoc indentation is currently incorrect.

Swagger relies on YAML formatting, and YAML is strictly indentation-based.
Hierarchy is determined by spaces — not formatting preference.

Example structure expectation:

/**
 * @swagger
 * /login:
 *   post:
 *     summary: User login
 *     tags:
 *       - Auth
 */

Make sure:

• post is indented under the route
• summary, tags, etc. are indented under post

If indentation is off, Swagger will silently fail to render sections correctly.

---

🔎 2. Scanner is Disabled

In Swagger.js, you currently have:

apis: []

This line overrides the route scanner completely.

To follow the intended hybrid approach:

• Remove apis: []
• Delete the hardcoded paths block in Swagger.js
• Move all route documentation into the respective route files

Right now, the scanner is effectively disabled, which defeats the purpose of shifting to JSDoc-based docs.

---

3. Duplicate Imports

In backend/index.js, it appears cookieParser has been imported twice.

Please remove the duplicate import to keep the entry file clean and maintainable.

---

Let’s fix these technical issues first. Once these are resolved, we’ll be in a strong position to merge.

Keep pushing - you’re on the right track.

[Aditya-18849]

hi @akshay0611 I have resolved all the requested changes! 🛠️

Fixed the YAML indentation in authRoutes.js.

Updated Swagger.js to use the auto-discovery scanner.

Removed the duplicate import in index.js.

Resolved all merge conflicts and passed the CI checks.

Ready for re-review!

[Aditya-18849]

@akshay0611 ??

[akshay0611]

The PRs would be reviewed before Monday EOD. Thanks & Regards Akshay Kumar

…

On Sat, Feb 14, 2026, 22:58 Aditya Patra ***@***.***> wrote: *Aditya-18849* left a comment (Nsanjayboruds/RIVETO#63) <#63 (comment)> @akshay0611 <https://github.com/akshay0611> ?? — Reply to this email directly, view it on GitHub <#63 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/ATTSBQ4N4CHXPHVCORBDB7T4L5LKFAVCNFSM6AAAAACUXAFN3GVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZTSMBSGIYDSMJTGE> . You are receiving this because you were mentioned.Message ID: ***@***.***>

[akshay0611]

Thanks for the follow-up updates. I re-verified locally and there are still blocking issues:

1. backend startup is currently broken:
   backend/index.js imports cookieParser twice, which throws:
   SyntaxError: Identifier 'cookieParser' has already been declared

2. Swagger auto-discovery is still effectively disabled:
   In backend/Swagger.js, apis is declared multiple times, and the final value is apis: [], which overrides the scanner config.

3. Route JSDoc is malformed and incomplete:
   backend/routes/authRoutes.js has invalid Swagger YAML indentation, and only one auth endpoint is documented inline while the previous hardcoded auth paths were removed.

Please fix these first, then I can re-verify for merge.

[Aditya-18849]

Okay

…

On Sun, Feb 15, 2026, 19:26 Akshay Kumar ***@***.***> wrote: ***@***.**** requested changes on this pull request. Thanks for the follow-up updates. I re-verified locally and there are still blocking issues: 1. backend startup is currently broken: backend/index.js imports cookieParser twice, which throws: SyntaxError: Identifier 'cookieParser' has already been declared 2. Swagger auto-discovery is still effectively disabled: In backend/Swagger.js, apis is declared multiple times, and the final value is apis: [], which overrides the scanner config. 3. Route JSDoc is malformed and incomplete: backend/routes/authRoutes.js has invalid Swagger YAML indentation, and only one auth endpoint is documented inline while the previous hardcoded auth paths were removed. Please fix these first, then I can re-verify for merge. — Reply to this email directly, view it on GitHub <#63 (review)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/BQCKDZVLOY55KFTLMNICXUL4MB3J5AVCNFSM6AAAAACUXAFN3GVHI2DSMVQWIX3LMV43YUDVNRWFEZLROVSXG5CSMV3GSZLXHMZTQMBUHA3TIOBYGE> . You are receiving this because you were mentioned.Message ID: ***@***.***>

[Aditya-18849]

hi @akshay0611 as you have asked for the changes , here is the updated pr , ready for review!!

thanks

[Aditya-18849]

Hi @akshay0611 any update???

[akshay0611]

Thanks for the update @Aditya-18849 . I re-verified PR #63 at the latest commit and there are still blockers before merge:

1. backend/index.js duplicate cookieParser import is fixed. Good.

2. Swagger scanner is still disabled:
   backend/Swagger.js still has apis: [], so auto-discovery from route files is not active.

3. Documentation coverage is still incomplete:
   backend/routes/authRoutes.js exposes 5 auth endpoints (/registration, /login, /logout, /googlelogin, /adminlogin), but backend/Swagger.js currently documents only 2 endpoints (/registration, /login).

Please complete this before re-review:

• Enable scanner-based discovery (remove apis: [] and point apis to route files), and
• Ensure all auth endpoints are documented with valid Swagger structure.

Once these are fixed, I can do a quick final verification.

[Aditya-18849]

Hi @akshay0611 , made the requested changes :
Enabled Auto-Discovery in backend/Swagger.js

Updated the apis configuration array from [] to ['./routes/*.js'].

This allows the Swagger generator to parse JSDoc comments directly from the route files, ensuring documentation stays close to the code.

Completed Documentation in backend/routes/authRoutes.js

Added comprehensive JSDoc/YAML comments for the following 3 missing endpoints:

GET /api/auth/logout

POST /api/auth/googlelogin

POST /api/auth/adminlogin

Fixed strict YAML indentation issues that were previously causing Map keys must be unique errors during parsing.

Verification
Scanner Status: The server now starts without YAMLSemanticError.

UI Check: Browsing to /api-docs now displays all 5 Auth endpoints (Registration, Login, Logout, Google Login, Admin Login).

[akshay0611]

Hi @Aditya-18849, this PR currently has merge conflicts with main.
Please sync your branch and resolve conflicts, then I’ll re-review.

Suggested steps:

1. git fetch origin
2. git checkout <your-pr-branch>
3. git rebase origin/main (or merge origin/main into your branch)
4. Resolve all conflict markers (<<<<<<<, =======, >>>>>>>) carefully
5. git add <resolved-files>
6. git rebase --continue (if rebasing)
7. git push --force-with-lease (if rebasing)

After resolving:

• Ensure backend starts successfully
• Verify Swagger docs load correctly at /api-docs
• Re-run your checks and post an update here

Tag me once done.