Add JSDoc to API files; generate docs

Author: codestun

auth.js

@@ -6,17 +6,27 @@ const passport = require('passport');
 
 require('./passport'); // Your local passport file
 
-// Function to generate JWT token
+/**
+ * Generates a JWT token for a user.
+ * @param {Object} user - The user object for whom the token is being generated.
+ * @returns {string} JWT token.
+ */
 let generateJWTToken = (user) => {
   return jwt.sign(user, jwtSecret, {
-    subject: user.Name, // This is the Name you’re encoding in the JWT
-    expiresIn: '7d', // This specifies that the token will expire in 7 days
-    algorithm: 'HS256' // This is the algorithm used to "sign" or encode the values of the JWT
+    subject: user.Name, // The username encoded in the JWT
+    expiresIn: '7d', // Token expiration time
+    algorithm: 'HS256' // Algorithm used to encode the JWT
   });
 };
 
-/* ------ Post login. -------- */
+/* POST login route */
 module.exports = (router) => {
+  /**
+ * @route POST /login
+ * @description Authenticates a user and returns a JWT token upon successful authentication.
+ * @param {Object} req - The request object containing user credentials.
+ * @param {Object} res - The response object.
+ */
   router.post('/login', (req, res) => {
     passport.authenticate('local', { session: false }, (error, user, info) => {
       if (error || !user) {

index.js

@@ -1,3 +1,9 @@
+/**
+ * @fileoverview Module imports and initial setup for the movie-api application.
+ * This file sets up the express application, configures middleware, establishes database connections,
+ * and defines routes for handling HTTP requests.
+ */
+
 // Load necessary modules
 const express = require('express');
 const bodyParser = require('body-parser');
@@ -9,12 +15,19 @@ const Models = require('./models.js');
 const { check, validationResult } = require('express-validator');
 require("dotenv").config();
 
-// Set up express and body-parser
+/**
+ * @description Set up express and body-parser.
+ * This section configures the express application and sets up middleware
+ * for parsing JSON and URL-encoded data.
+ */
 const app = express();
 app.use(bodyParser.json());
 app.use(bodyParser.urlencoded({ extended: true }));
 
-// Set up CORS
+/**
+ * @description CORS setup to allow cross-origin requests.
+ * Specifies which domains are allowed to access the API.
+ */
 const cors = require('cors');
 let allowedOrigins = [
   'http://localhost:8080',
@@ -24,7 +37,6 @@ let allowedOrigins = [
   'https://myflickpick.netlify.app',
   'https://codestun.github.io'
 ];
-
 app.use(cors({
   origin: (origin, callback) => {
     if (!origin) return callback(null, true);
@@ -36,17 +48,26 @@ app.use(cors({
   }
 }));
 
-// Import "auth.js" file
+/**
+ * @description Import and setup authentication module.
+ * Integrates Passport for user authentication within the application.
+ */
 let auth = require('./auth')(app);
 
 // Require the Passport module and import the "passport.js" file
 const passport = require('passport');
 require('./passport');
 
-// Set up Morgan for logging functionality
+/**
+ * @description Morgan logging setup.
+ * Integrates Morgan for logging HTTP request data for debugging and monitoring.
+ */
 app.use(morgan('combined'));
 
-// Connect to the MongoDB database using the connection URI from environment variable
+/**
+ * @description Connects to the MongoDB database using Mongoose.
+ * The connection URI is retrieved from environment variables.
+ */
 mongoose.connect(process.env.CONNECTION_URI, { useNewUrlParser: true, useUnifiedTopology: true });
 
 // Connect to the MongoDB database using the local connection URI
@@ -59,7 +80,13 @@ const Movies = Models.Movie;
 const Users = Models.User;
 
 /* ------ Routes for Movies -------- */
-// Return JSON object containing data about all movies
+
+/**
+ * @route GET /movies
+ * @description Returns a JSON object containing data about all movies.
+ * @access Private
+ * @returns {Object[]} movies - List of all movies.
+ */
 app.get('/movies', passport.authenticate('jwt', { session: false }), (req, res) => {
   Movies.find()
     .then((movies) => {
@@ -71,7 +98,13 @@ app.get('/movies', passport.authenticate('jwt', { session: false }), (req, res)
     });
 });
 
-// Return JSON object containing data about a single movie by title
+/**
+ * @route GET /movies/:Title
+ * @description Returns data about a single movie by title.
+ * @access Private
+ * @param {string} Title - Title of the movie.
+ * @returns {Object} movie - Data about the movie.
+ */
 app.get('/movies/:Title', passport.authenticate('jwt', { session: false }), (req, res) => {
   Movies.findOne({ Title: req.params.Title })
     .then((movie) => {
@@ -83,7 +116,13 @@ app.get('/movies/:Title', passport.authenticate('jwt', { session: false }), (req
     });
 });
 
-// Return data about a genre (description) by name/title (e.g., "Rock")
+/**
+ * @route GET /genres/:Name
+ * @description Returns data about a specific genre by name.
+ * @access Private
+ * @param {string} Name - Name of the genre.
+ * @returns {Object} genre - Description of the genre.
+ */
 app.get('/genres/:Name', passport.authenticate('jwt', { session: false }), (req, res) => {
   Movies.findOne({ "Genre.Name": req.params.Name })
     .then((movie) => {
@@ -99,7 +138,13 @@ app.get('/genres/:Name', passport.authenticate('jwt', { session: false }), (req,
     });
 });
 
-// Return data about a director by name
+/**
+ * @route GET /directors/:Name
+ * @description Returns data about a director by name.
+ * @access Private
+ * @param {string} Name - Name of the director.
+ * @returns {Object} director - Data about the director.
+ */
 app.get('/directors/:Name', passport.authenticate('jwt', { session: false }), (req, res) => {
   Movies.findOne({ "Director.Name": req.params.Name })
     .then((movie) => {
@@ -116,7 +161,13 @@ app.get('/directors/:Name', passport.authenticate('jwt', { session: false }), (r
 });
 
 /* ------ Routes for Users -------- */
-// Return JSON object containing data about all users
+
+/**
+ * @route GET /users
+ * @description Returns a list of all users.
+ * @access Private
+ * @returns {Object[]} users - List of all users.
+ */
 app.get('/users', passport.authenticate('jwt', { session: false }), (req, res) => {
   Users.find()
     .then((users) => {
@@ -128,7 +179,13 @@ app.get('/users', passport.authenticate('jwt', { session: false }), (req, res) =
     });
 });
 
-// Return JSON object containing data about a single user by name
+/**
+ * @route GET /users/:Name
+ * @description Returns data about a single user by name.
+ * @access Private
+ * @param {string} Name - Name of the user.
+ * @returns {Object} user - Data about the user.
+ */
 app.get('/users/:Name', passport.authenticate('jwt', { session: false }), (req, res) => {
   Users.findOne({ Name: req.params.Name })
     .then((user) => {
@@ -140,7 +197,16 @@ app.get('/users/:Name', passport.authenticate('jwt', { session: false }), (req,
     });
 });
 
-// Allow new users to register
+/**
+ * @route POST /users
+ * @description Allows new users to register.
+ * @access Public
+ * @param {string} Name - User's name.
+ * @param {string} Email - User's email.
+ * @param {string} Password - User's password.
+ * @param {Date} Birthday - User's birthday.
+ * @returns {Object} user - The registered user object.
+ */
 app.post('/users', [
   check('Name', 'Name is required').notEmpty(),
   check('Email', 'Email does not appear to be valid').isEmail(),
@@ -184,7 +250,16 @@ app.post('/users', [
 });
 
 
-// Allow users to update their user info
+/**
+ * @route PUT /users/:Name
+ * @description Allows users to update their information.
+ * @access Private
+ * @param {string} Name - User's updated name.
+ * @param {string} Email - User's updated email.
+ * @param {string} Password - User's updated password.
+ * @param {Date} Birthday - User's updated birthday.
+ * @returns {Object} updatedUser - The updated user object.
+ */
 app.put('/users/:Name', [
   check('Name', 'Name is required').notEmpty(),
   check('Email', 'Email does not appear to be valid').isEmail(),
@@ -221,7 +296,14 @@ app.put('/users/:Name', [
     });
 });
 
-// Allow users to add a movie to their list of favorites
+/**
+ * @route POST /users/:Name/movies/:MovieID
+ * @description Allows users to add a movie to their list of favorites.
+ * @access Private
+ * @param {string} Name - User's name.
+ * @param {string} MovieID - ID of the movie to add to favorites.
+ * @returns {Object} updatedUser - The user object with updated favorites list.
+ */
 app.post('/users/:Name/movies/:MovieID', passport.authenticate('jwt', { session: false }), (req, res) => {
   Users.findOneAndUpdate(
     { Name: req.params.Name },
@@ -236,7 +318,14 @@ app.post('/users/:Name/movies/:MovieID', passport.authenticate('jwt', { session:
     });
 });
 
-// Allow users to remove a movie from their list of favorites
+/**
+ * @route DELETE /users/:Name/movies/:MovieID
+ * @description Allows users to remove a movie from their list of favorites.
+ * @access Private
+ * @param {string} Name - User's name.
+ * @param {string} MovieID - ID of the movie to remove from favorites.
+ * @returns {Object} updatedUser - The user object with updated favorites list.
+ */
 app.delete('/users/:Name/movies/:MovieID', passport.authenticate('jwt', { session: false }), (req, res) => {
   Users.findOneAndUpdate(
     { Name: req.params.Name },
@@ -251,7 +340,13 @@ app.delete('/users/:Name/movies/:MovieID', passport.authenticate('jwt', { sessio
     });
 });
 
-// Allow existing users to deregister
+/**
+ * @route DELETE /users/:Name
+ * @description Allows existing users to deregister.
+ * @access Private
+ * @param {string} Name - Name of the user to deregister.
+ * @returns {string} message - Confirmation message of user deletion.
+ */
 app.delete('/users/:Name', passport.authenticate('jwt', { session: false }), (req, res) => {
   Users.findOneAndRemove({ Name: req.params.Name })
     .then((user) => {
@@ -268,17 +363,31 @@ app.delete('/users/:Name', passport.authenticate('jwt', { session: false }), (re
 });
 
 /* ------ Other Routes -------- */
-// Default text response
+/**
+ * @route GET /
+ * @description Default route to welcome users.
+ * @access Public
+ * @returns {string} message - Welcome message.
+ */
 app.get('/', (req, res) => {
-  res.send('Welcome to flickPick!');
+  res.send('Welcome to FlickPick!');
 });
 
-// Documentation endpoint
+/**
+ * @route GET /documentation
+ * @description Serves the API documentation file.
+ * @access Public
+ * @returns {file} - Sends the documentation HTML file.
+ */
 app.get('/documentation', (req, res) => {
   res.sendFile(path.join(__dirname, 'public', 'documentation.html'));
 });
 
-// Error-handling middleware
+/**
+ * @description Error handling middleware.
+ * Handles any errors that occur in the routing and request handling process.
+ */
+
 app.use((err, req, res, next) => {
   // Log error to the terminal
   console.error(err);
@@ -287,7 +396,10 @@ app.use((err, req, res, next) => {
   res.status(500).send('Internal Server Error');
 });
 
-// Listen for connections
+/**
+ * @description Initializes and starts the server on a specified port.
+ * The port number is obtained from environment variables or defaults to 8080.
+ */
 const port = process.env.PORT || 8080;
 app.listen(port, '0.0.0.0', () => {
   console.log('Listening on Port ' + port);