Add Swagger docs for Account, Carts and Checkouts

package.json

@@ -21,12 +21,14 @@
     "hapi": "11.1.4",
     "hapi-async-handler": "1.0.3",
     "hapi-auth-jwt2": "5.8.0",
+    "hapi-swagger": "^6.2.2",
     "inert": "3.2.0",
     "joi": "6.10.1",
     "jsonwebtoken": "5.7.0",
     "node-uuid": "1.4.7",
     "request": "2.71.0",
-    "rethinkdbdash": "2.2.18"
+    "rethinkdbdash": "2.2.18",
+    "vision": "^4.1.0"
   },
   "devDependencies": {
     "nodemon": "1.9.1"

src/resources/account/routes.js

@@ -24,6 +24,8 @@ export default [
         config: {
             handler: {async: AccountHandlers.get},
             auth: {strategy: 'jwt'},
+            description: 'Get user account details',
+            tags: ['api'],
             response: {
                 schema: AccountDetailsSerializer.schema
             }
@@ -35,6 +37,8 @@ export default [
         config: {
             handler: {async: AccountHandlers.patch},
             auth: {strategy: 'jwt'},
+            description: 'Update account details',
+            tags: ['api'],
             response: {
                 schema: AccountDetailsSerializer.schema
             }
@@ -45,6 +49,8 @@ export default [
         method: 'POST',
         config: {
             handler: {async: AccountLoginHandlers.post},
+            description: 'Create login session',
+            tags: ['api'],
             validate: {
                 payload: {
                     email: Joi.string().required(),
@@ -58,6 +64,8 @@ export default [
         method: 'POST',
         config: {
             handler: {async: AccountRegisterHandlers.post},
+            description: 'Register a new account',
+            tags: ['api'],
             validate: {
                 payload: {
                     name: Joi.string().required(),
@@ -72,6 +80,10 @@ export default [
         method: 'PATCH',
         config: {
             handler: {async: AccountRegisterHandlers.patch},
+            description: 'Activate account',
+            notes: 'When an account is registered, an email is sent with a link to confirm the user\'s email. ' +
+                'That link contains a token used to activate the newly registered account.',
+            tags: ['api'],
             validate: {
                 payload: {
                     token: Joi.string().required()
@@ -89,6 +101,8 @@ export default [
         method: 'POST',
         config: {
             handler: {async: AccountResetHandlers.post},
+            description: 'Request password reset',
+            tags: ['api'],
             validate: {
                 payload: {
                     email: Joi.string().required()
@@ -101,6 +115,8 @@ export default [
         method: 'PATCH',
         config: {
             handler: {async: AccountResetHandlers.patch},
+            description: 'Reset password',
+            tags: ['api'],
             validate: {
                 payload: {
                     token: Joi.string().required(),

src/resources/carts/routes.js

@@ -1,6 +1,8 @@
 /**
  * Imports
  */
+import Joi from 'joi';
+
 import routePrerequisites from './routePrerequisites';
 
 // Data schemas
@@ -36,6 +38,8 @@ export default [
                 mode: 'try',
                 strategy: 'jwt'
             },
+            description: 'Create a new shopping cart',
+            tags: ['api'],
             response: {
                 schema: CartSerializer.schema
             }
@@ -50,7 +54,15 @@ export default [
                 mode: 'try',
                 strategy: 'jwt'
             },
+            description: 'Get cart',
+            notes: 'Returns a cart by the id passed in the path',
+            tags: ['api'],
             pre: [routePrerequisites.validCartAndPermissions],
+            validate: {
+                params: {
+                    cartId: Joi.string().required().description('the id for the cart'),
+                }
+            },
             response: {
                 schema: CartSerializer.schema
             }
@@ -65,7 +77,14 @@ export default [
                 mode: 'try',
                 strategy: 'jwt'
             },
+            description: 'Update cart',
+            tags: ['api'],
             pre: [routePrerequisites.validCartAndPermissions],
+            validate: {
+                params: {
+                    cartId: Joi.string().required().description('the id for the cart'),
+                }
+            },
             response: {
                 schema: CartSerializer.schema
             }

src/resources/checkouts/routes.js

@@ -38,6 +38,8 @@ export default [
                 mode: 'try',
                 strategy: 'jwt'
             },
+            description: 'Create a new checkout',
+            tags: ['api'],
             validate: {
                 payload: {
                     cartId: Joi.string().required(),
@@ -59,7 +61,15 @@ export default [
                 mode: 'try',
                 strategy: 'jwt'
             },
+            description: 'Get checkout',
+            notes: 'Returns a checkout by the id passed in the path',
+            tags: ['api'],
             pre: [routePrerequisites.validCheckoutAndPermissions],
+            validate: {
+                params: {
+                    checkoutId: Joi.string().required().description('the id for the checkout'),
+                }
+            },
             response: {
                 schema: CheckoutSerializer.schema
             }
@@ -74,7 +84,14 @@ export default [
                 mode: 'try',
                 strategy: 'jwt'
             },
+            description: 'Update checkout',
+            tags: ['api'],
             pre: [routePrerequisites.validCheckoutAndPermissions],
+            validate: {
+                params: {
+                    checkoutId: Joi.string().required().description('the id for the checkout'),
+                }
+            },
             response: {
                 schema: CheckoutSerializer.schema
             }

src/server.js

@@ -2,7 +2,9 @@
  * Imports
  */
 import Hapi from 'hapi';
+import HapiSwagger from 'hapi-swagger';
 import Inert from 'inert';
+import Vision from 'vision';
 
 import config from './config';
 import log from './logging';
@@ -33,6 +35,38 @@ server.connection({
     }
 });
 
+// Swagger API Documentation
+const Pack = require('../package');
+server.register([Inert, Vision, {
+    register: HapiSwagger,
+    options: {
+        info: {
+            title: 'ATLAS API Documentation',
+            version: Pack.version,
+        },
+        documentationPath: `${config.app.routePrefix || ''}/docs`,
+        pathReplacements: [{
+            replaceIn: 'groups',
+            pattern: /v([0-9]+)\//,
+            replacement: ''
+        }],
+        tags: [{
+            name: 'account',
+            description: 'Customer accounts'
+        }, {
+            name: 'carts',
+            description: 'Product shopping carts'
+        }, {
+            name: 'checkouts',
+            description: 'Checkout a cart'
+        }]
+    }
+}], function (err) {
+    if (err) {
+        log.warn(err, 'Unable to setup Swagger API documentation');
+    }
+});
+
 // Enable async/await handlers
 server.register(require('hapi-async-handler'), function (err) {
     if (err) {
@@ -67,7 +101,7 @@ server.on('request-error', function (request, err) {
  */
 server.route({
     method: 'GET',
-    path: '/',
+    path: config.app.routePrefix || '/',
     handler: function (request, reply) {
         reply('oh, hai');
     }
@@ -105,7 +139,7 @@ db.testDatabase().then(function successFn() {
         if (err) {
             log.fatal(err, 'Unable to start Atlas server');
         } else {
-            log.info('Atlas running at:', server.info.uri);
+            log.info(`Atlas running at: ${server.info.uri}${config.app.routePrefix || ''}`);
         }
     });
 }, function errorFn(err) {