Add Swagger API Documentation using swagger-ui-express and swagger-autogen

[akash-kumar-dev]

Summary

Integrate Swagger API documentation into the BrowsePing backend using swagger-ui-express and swagger-autogen, ensuring compatibility with the current codebase.

Details

• Add API documentation using Swagger UI so that developers can easily browse and test endpoints.
• Use swagger-autogen for automatic generation of the Swagger JSON documentation from JSDoc/TSDoc comments in the codebase.
• Expose Swagger UI at a route such as /docs or /api-docs.
• Ensure minimal refactoring—prioritize compatibility with the existing Express.js/TypeScript application and folder structure.
• Only generate Swagger documentation JSON locally (do not commit generated JSON to repo).
• Add generated Swagger files to .gitignore / ensure no docs or generated JSON are pushed.

Implementation Suggestions

• Install swagger-ui-express and swagger-autogen as devDependencies.
• Create a standalone script file for documentation generation.
• Add an npm script (e.g., npm run generate:swagger) to generate the documentation locally.
• The API docs UI (/docs or /api-docs) should only appear when the Swagger JSON is present and should NOT be exposed in production.
• Swagger docs must NOT break the server if the docs are not generated or not present.
• Production server (npm run start) must not require or serve Swagger docs.
• Add .env variable to control docs UI; default to enabled only for development/local environment.
• users must generate docs locally; do not add generated files to version control.
• Follow minimal-change principle—do not refactor existing routes beyond what's necessary for Swagger integration.

SWoC Friendly Guidance

• Reference open source examples where Swagger docs are optional/local-only.
• Keep the PR atomic and focused.
• Confirm that production flow is untouched for users who do not generate docs.
• Ask for help in Discord if you hit any blockers.

While working on this issue, please adhere to the guidelines outlined in contributing.md. Any pull requests that do not follow these rules will be marked as invalid.

[trivedikavya]

Hi @akash-kumar-dev ,

I would like to work on this issue. I have reviewed the requirements and here is how I plan to implement the solution:

1. Dependencies: Install swagger-ui-express and swagger-autogen as devDependencies.
2. Generation Script: Create a standalone swagger.js script to auto-generate the Swagger JSON file.
3. NPM Script: Add a npm run generate:swagger command to package.json.
4. Server Integration: Update src/index.ts to serve the UI at /api-docs. I will ensure the route only activates if the JSON file exists, so it does not affect production or crash if the docs aren't generated.
5. Git Ignore: Add the generated JSON file to .gitignore to ensure it is not pushed to the repository.

Please assign this issue to me. I am ready to get started!

[akash-kumar-dev]

Looks good, @trivedikavya ! We're looking forward to seeing your solution. Please raise a related PR for this.

[vishal0316]

@akash-kumar-dev should i work on this Issue And Create PR?

[akash-kumar-dev]

Yes, @vishal0316 , you can work on this issue and open a PR.

[vishal0316]

Yes, @vishal0316 , you can work on this issue and open a PR.

Thanks

[SujalTripathi]

Hey @akash-kumar-dev can i work on these issue?