Add remaining Swagger docs and update README

oomag · Aug 23, 2016 · 0e36b0e · 0e36b0e
1 parent f6d27a6
commit 0e36b0e
Show file tree

Hide file tree

Showing 12 changed files with 249 additions and 12 deletions.
diff --git a/README.md b/README.md
@@ -1,18 +1,33 @@
 # Welcome
-Atlas is an E-Commerce Backend API that provides services for:
+Atlas is an E-Commerce Backend (RESTful) API.
+
+It was built with the [Yoonic E-Commerce Storefront](https://github.com/yoonic/nicistore) application in mind and you can check it out live powering [NICI Store](https://nicistore.com)!
+
+> Why write plugins when you can build your own e-commerce platform?
+
+![Swagger API Documentation](/screenshots/SwaggerDocs.png?raw=true "Swagger API Documentation")
+
+### API Resources
+After deploying and running Atlas locally, you can access the [Swagger](https://openapis.org/) API Documentation by browsing to `localhost:8000/docs`.
+
+Overall, Atlas provides services for:
 
 - User Accounts
-- Contents (think of it as a mini CMS)
+- Contents
+  - Homepage Banners
+  - Articles
+  - Content common to all Product Pages
+  - ... <-- Whatever you wish :)
 - Products
-- Collections (group of Products, Contents, Users)
+- Collections
+  - Products
+  - Contents
+  - Customers
+  - ... <-- Your own segmentation engine!
 - Carts
 - Checkouts
 - Orders
 
-It was built with the [Yoonic E-Commerce Storefront](https://github.com/yoonic/nicistore) application in mind and you can check it out live powering [NICI Store](https://nicistore.com)!
-
-> Why build plugins when you can build your own e-commerce platform?
-
 ## Requirements
 
 - Node.js + NPM (v4.x LTS)

diff --git a/screenshots/SwaggerDocs.png b/screenshots/SwaggerDocs.png
diff --git a/src/resources/account/routes.js b/src/resources/account/routes.js
@@ -26,6 +26,11 @@ export default [
             auth: {strategy: 'jwt'},
             description: 'Get user account details',
             tags: ['api'],
+            validate: {
+                headers: Joi.object({
+                    'authorization': Joi.string().required()
+                }).unknown()
+            },
             response: {
                 schema: AccountDetailsSerializer.schema
             }
@@ -39,6 +44,11 @@ export default [
             auth: {strategy: 'jwt'},
             description: 'Update account details',
             tags: ['api'],
+            validate: {
+                headers: Joi.object({
+                    'authorization': Joi.string().required()
+                }).unknown()
+            },
             response: {
                 schema: AccountDetailsSerializer.schema
             }

diff --git a/src/resources/carts/routes.js b/src/resources/carts/routes.js
@@ -40,6 +40,11 @@ export default [
             },
             description: 'Create a new shopping cart',
             tags: ['api'],
+            validate: {
+                headers: Joi.object({
+                    'authorization': Joi.string().optional()
+                }).unknown()
+            },
             response: {
                 schema: CartSerializer.schema
             }
@@ -59,6 +64,9 @@ export default [
             tags: ['api'],
             pre: [routePrerequisites.validCartAndPermissions],
             validate: {
+                headers: Joi.object({
+                    'authorization': Joi.string().optional()
+                }).unknown(),
                 params: {
                     cartId: Joi.string().required().description('the id for the cart'),
                 }
@@ -81,6 +89,9 @@ export default [
             tags: ['api'],
             pre: [routePrerequisites.validCartAndPermissions],
             validate: {
+                headers: Joi.object({
+                    'authorization': Joi.string().optional()
+                }).unknown(),
                 params: {
                     cartId: Joi.string().required().description('the id for the cart'),
                 }

diff --git a/src/resources/checkouts/routes.js b/src/resources/checkouts/routes.js
@@ -41,6 +41,9 @@ export default [
             description: 'Create a new checkout',
             tags: ['api'],
             validate: {
+                headers: Joi.object({
+                    'authorization': Joi.string().optional()
+                }).unknown(),
                 payload: {
                     cartId: Joi.string().required(),
                     shippingAddress: Joi.object().optional(),
@@ -66,6 +69,9 @@ export default [
             tags: ['api'],
             pre: [routePrerequisites.validCheckoutAndPermissions],
             validate: {
+                headers: Joi.object({
+                    'authorization': Joi.string().optional()
+                }).unknown(),
                 params: {
                     checkoutId: Joi.string().required().description('the id for the checkout'),
                 }
@@ -88,6 +94,9 @@ export default [
             tags: ['api'],
             pre: [routePrerequisites.validCheckoutAndPermissions],
             validate: {
+                headers: Joi.object({
+                    'authorization': Joi.string().optional()
+                }).unknown(),
                 params: {
                     checkoutId: Joi.string().required().description('the id for the checkout'),
                 }

diff --git a/src/resources/collections/routes.js b/src/resources/collections/routes.js
@@ -22,7 +22,12 @@ export default [
                 mode: 'try',
                 strategy: 'jwt'
             },
+            description: 'Get all the collections',
+            tags: ['api'],
             validate: {
+                headers: Joi.object({
+                    'authorization': Joi.string().optional()
+                }).unknown(),
                 query: {
                     tags: Joi.string().optional()
                 }
@@ -38,7 +43,12 @@ export default [
                 strategy: 'jwt',
                 scope: ['admin']
             },
+            description: 'Create new collection',
+            tags: ['api'],
             validate: {
+                headers: Joi.object({
+                    'authorization': Joi.string().required()
+                }).unknown(),
                 payload: {
                     name: Joi.object().required(),
                     tags: Joi.array().required()
@@ -61,6 +71,17 @@ export default [
             auth: {
                 mode: 'try',
                 strategy: 'jwt'
+            },
+            description: 'Get collection',
+            notes: 'Returns a collection by the id passed in the path',
+            tags: ['api'],
+            validate: {
+                headers: Joi.object({
+                    'authorization': Joi.string().optional()
+                }).unknown(),
+                params: {
+                    collectionId: Joi.string().required().description('the id for the collection'),
+                }
             }
         }
     },
@@ -73,7 +94,15 @@ export default [
                 strategy: 'jwt',
                 scope: ['admin']
             },
+            description: 'Update collection',
+            tags: ['api'],
             validate: {
+                headers: Joi.object({
+                    'authorization': Joi.string().required()
+                }).unknown(),
+                params: {
+                    collectionId: Joi.string().required().description('the id for the collection'),
+                },
                 payload: {
                     enabled: Joi.boolean().required(),
                     name: Joi.object({

diff --git a/src/resources/contents/routes.js b/src/resources/contents/routes.js
@@ -26,7 +26,12 @@ export default [
                 mode: 'try',
                 strategy: 'jwt'
             },
+            description: 'Get contents collection',
+            tags: ['api'],
             validate: {
+                headers: Joi.object({
+                    'authorization': Joi.string().optional()
+                }).unknown(),
                 query: {
                     type: Joi.string().optional(),
                     tags: Joi.string().optional(),
@@ -44,7 +49,12 @@ export default [
                 strategy: 'jwt',
                 scope: ['admin']
             },
+            description: 'Create new content',
+            tags: ['api'],
             validate: {
+                headers: Joi.object({
+                    'authorization': Joi.string().required()
+                }).unknown(),
                 payload: {
                     type: Joi.string().required(),
                     name: Joi.object().required()
@@ -68,6 +78,16 @@ export default [
                 mode: 'try',
                 strategy: 'jwt'
             },
+            description: 'Get content',
+            tags: ['api'],
+            validate: {
+                headers: Joi.object({
+                    'authorization': Joi.string().optional()
+                }).unknown(),
+                params: {
+                    contentId: Joi.string().required().description('the id for the content'),
+                },
+            },
             response: {
                 schema: ContentSerializer.schema
             }
@@ -82,7 +102,15 @@ export default [
                 strategy: 'jwt',
                 scope: ['admin']
             },
+            description: 'Update content',
+            tags: ['api'],
             validate: {
+                headers: Joi.object({
+                    'authorization': Joi.string().required()
+                }).unknown(),
+                params: {
+                    contentId: Joi.string().required().description('the id for the content'),
+                },
                 payload: {
                     enabled: Joi.boolean().required(),
                     collections: Joi.array().required(),
@@ -108,7 +136,15 @@ export default [
             auth: {
                 strategy: 'jwt'
             },
+            description: 'Add user comment',
+            tags: ['api'],
             validate: {
+                headers: Joi.object({
+                    'authorization': Joi.string().required()
+                }).unknown(),
+                params: {
+                    contentId: Joi.string().required().description('the id for the content'),
+                },
                 payload: {
                     message: Joi.string().required()
                 }

diff --git a/src/resources/files/routes.js b/src/resources/files/routes.js
@@ -19,12 +19,17 @@ export default [
                 strategy: 'jwt',
                 scope: ['admin']
             },
+            description: 'Upload file',
+            tags: ['api'],
             payload: {
                 maxBytes: 10048576,
                 output: 'stream',
                 parse: true
             },
             validate: {
+                headers: Joi.object({
+                    'authorization': Joi.string().required()
+                }).unknown(),
                 payload: {
                     file: Joi.object().required(),
                     resource: Joi.string().required()

diff --git a/src/resources/orders/routes.js b/src/resources/orders/routes.js
@@ -27,6 +27,13 @@ export default [
             handler: {async: OrdersHandler.get},
             auth: {
                 strategy: 'jwt'
+            },
+            description: 'Get orders collection',
+            tags: ['api'],
+            validate: {
+                headers: Joi.object({
+                    'authorization': Joi.string().required()
+                }).unknown(),
             }
         }
     },
@@ -39,7 +46,12 @@ export default [
                 mode: 'try',
                 strategy: 'jwt'
             },
+            description: 'Create a new order',
+            tags: ['api'],
             validate: {
+                headers: Joi.object({
+                    'authorization': Joi.string().optional()
+                }).unknown(),
                 payload: {
                     checkoutId: Joi.string().required()
                 }
@@ -57,7 +69,17 @@ export default [
             auth: {
                 strategy: 'jwt'
             },
-            pre: [routePrerequisites.validOrder]
+            description: 'Get order',
+            tags: ['api'],
+            pre: [routePrerequisites.validOrder],
+            validate: {
+                headers: Joi.object({
+                    'authorization': Joi.string().required()
+                }).unknown(),
+                params: {
+                    orderId: Joi.string().required().description('the id for the order'),
+                }
+            }
         }
     },
     {
@@ -69,7 +91,17 @@ export default [
                 strategy: 'jwt',
                 scope: ['admin']
             },
-            pre: [routePrerequisites.validOrder]
+            description: 'Update order',
+            tags: ['api'],
+            pre: [routePrerequisites.validOrder],
+            validate: {
+                headers: Joi.object({
+                    'authorization': Joi.string().required()
+                }).unknown(),
+                params: {
+                    orderId: Joi.string().required().description('the id for the order'),
+                }
+            }
         }
     },
     {
@@ -81,7 +113,16 @@ export default [
                 strategy: 'jwt',
                 scope: ['admin']
             },
+            description: 'Send transactional email',
+            notes: 'This endpoint enables manual triggering of certain transactional emails',
+            tags: ['api'],
             validate: {
+                headers: Joi.object({
+                    'authorization': Joi.string().required()
+                }).unknown(),
+                params: {
+                    orderId: Joi.string().required().description('the id for the order'),
+                },
                 payload: {
                     template: Joi.string().required(),
                     email: Joi.string().required(),
@@ -94,7 +135,15 @@ export default [
         path: '/{orderId}/spwh',
         method: 'POST',
         config: {
-            handler: {async: SwitchPaymentsWebhookHandler.post}
+            handler: {async: SwitchPaymentsWebhookHandler.post},
+            description: 'Switch Payments webhook',
+            tags: ['api'],
+            validate: {
+                params: {
+                    orderId: Joi.string().required().description('the id for the order'),
+                }
+            }
+
         }
     }
 ];