Added swagger-jsdoc (#63)

Tags is currently todo

Author: joshmorel

CONTRIBUTING.md

@@ -7,3 +7,4 @@ For contributing to this project, please:
 * clone the repository
 * make changes
 * submit a pull request with a unit test on `develop` branch
+* document paths, params (in controllers) & definitions (in models) using [swagger-jsdoc](https://github.com/Surnet/swagger-jsdoc/blob/master/docs/GETTING-STARTED.md) which will be served at http{s}://host:port/api/docs

README.md

@@ -14,7 +14,7 @@ The backend services and API for the Software Engineering Daily [Android](https:
   - `npm start` or `yarn start`
   - check package.json for other builds
   - use curl or Postman to make requests
-
+  - view swagger api docs at HOST/api/docs
 
 ## Using Docker
   - `cp .env.docker_example .env`

config/express.js

@@ -52,6 +52,7 @@ if (config.env === 'development') {
 // mount all routes on /api path
 app.use('/api', routes);
 
+
 // if error is not an instanceOf APIError, convert it.
 app.use((err, req, res, next) => {
   if (err instanceof expressValidation.ValidationError) {

gulpfile.babel.js

@@ -7,22 +7,27 @@ import runSequence from 'run-sequence';
 const plugins = gulpLoadPlugins();
 
 const paths = {
-  js: ['./**/*.js', '!dist/**', '!node_modules/**', '!coverage/**'],
-  nonJs: ['./package.json', './.gitignore', './.env'],
+  js: ['./**/*.js', '!dist/**', '!node_modules/**', '!coverage/**', '!./server/docs/**'],
+  nonJs: ['./package.json', './.gitignore', './.env', './server/**/static/**'],
+  docs: ['./server/docs/**'],
   tests: './server/tests/*.js'
 };
 
 // Clean up dist and coverage directory
 gulp.task('clean', () =>
-  del.sync(['dist/**', 'dist/.*', 'coverage/**', '!dist', '!coverage'])
-);
+  del.sync(['dist/**', 'dist/.*', 'coverage/**', '!dist', '!coverage']));
 
 // Copy non-js files to dist
 gulp.task('copy', () =>
   gulp.src(paths.nonJs)
     .pipe(plugins.newer('dist'))
-    .pipe(gulp.dest('dist'))
-);
+    .pipe(gulp.dest('dist')));
+
+// Copy docs to dist
+gulp.task('docs', () =>
+  gulp.src(paths.docs)
+    .pipe(plugins.newer('dist/server/docs'))
+    .pipe(gulp.dest('dist/server/docs')));
 
 // Compile ES6 to ES5 and copy to dist
 gulp.task('babel', () =>
@@ -36,26 +41,22 @@ gulp.task('babel', () =>
         return path.relative(file.path, __dirname);
       }
     }))
-    .pipe(gulp.dest('dist'))
-);
+    .pipe(gulp.dest('dist')));
 
 // Start server with restart on file changes
-gulp.task('nodemon', ['copy', 'babel'], () =>
+gulp.task('nodemon', ['copy', 'docs', 'babel'], () =>
   plugins.nodemon({
     script: path.join('dist', 'index.js'),
     ext: 'js',
     ignore: ['node_modules/**/*.js', 'dist/**/*.js'],
-    tasks: ['copy', 'babel'],
+    tasks: ['copy', 'docs', 'babel'],
     legacyWatch: true
-  })
-);
+  }));
 
 // gulp serve for development
 gulp.task('serve', ['clean'], () => runSequence('nodemon'));
 
 // default task: clean dist, compile js files and copy non-js files.
 gulp.task('default', ['clean'], () => {
-  runSequence(
-    ['copy', 'babel']
-  );
+  runSequence(['copy', 'docs', 'babel']);
 });