From f6d27a6bc0b1f83bacc3af8abe907eff49a806d7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Andre=CC=81=20Tavares?= Date: Tue, 23 Aug 2016 00:12:59 +0100 Subject: [PATCH] Add Swagger docs for Account, Carts and Checkouts --- package.json | 4 +++- src/resources/account/routes.js | 16 +++++++++++++ src/resources/carts/routes.js | 19 ++++++++++++++++ src/resources/checkouts/routes.js | 17 ++++++++++++++ src/server.js | 38 +++++++++++++++++++++++++++++-- 5 files changed, 91 insertions(+), 3 deletions(-) diff --git a/package.json b/package.json index b1cb8bf..5a1c325 100644 --- a/package.json +++ b/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" diff --git a/src/resources/account/routes.js b/src/resources/account/routes.js index 92857fa..9c0eb57 100644 --- a/src/resources/account/routes.js +++ b/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(), diff --git a/src/resources/carts/routes.js b/src/resources/carts/routes.js index 19bf50e..196eb57 100644 --- a/src/resources/carts/routes.js +++ b/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 } diff --git a/src/resources/checkouts/routes.js b/src/resources/checkouts/routes.js index a11d18e..7e7bf7e 100644 --- a/src/resources/checkouts/routes.js +++ b/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 } diff --git a/src/server.js b/src/server.js index 6df1394..e157875 100644 --- a/src/server.js +++ b/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) {