Merge pull request #40 from olusoladavid/ch-update-documentation-1598…

…92381 #159892381 Update API documentation and project README
olusoladavid · Aug 20, 2018 · 22566b5 · 22566b5
2 parents ffe61cb + f524023
commit 22566b5
Show file tree

Hide file tree

Showing 3 changed files with 146 additions and 41 deletions.
diff --git a/README.md b/README.md
@@ -34,6 +34,7 @@ MyDiary is an online journal where users can pen down their thoughts and feeling
 | POST `/auth/signup`         | Register a user      |
 | POST `/auth/login`          | Login a user         |
 | GET `/profile`              | Fetch user profile   |
+| PUT `/profile`              | Update user profile  |
 | GET `/entries`              | Fetch all entries    |
 | GET `/entries/<entryId>`    | Fetch a single entry |
 | POST `/entries`             | Create an entry      |
@@ -43,18 +44,18 @@ MyDiary is an online journal where users can pen down their thoughts and feeling
 ## Build Setup
 
 ```
-#clone repo and cd into directory
+# Clone repo and cd into directory
 git clone https://github.com/olusoladavid/my-diary.git
 ```
 
 ```
-# install dependencies
+# Install dependencies
 npm install
 
-#serve in development environment
+# Serve in development environment
 npm run dev
 
-# build for production
+# Build for production
 npm run build
 ```
 
@@ -65,9 +66,13 @@ npm run build
 npm test
 ```
 
+## Links
+
+Documentation: https://my-diary-api.herokuapp.com/api/docs
+
 API Endpoint: https://my-diary-api.herokuapp.com/api/v1
 
-UI Template: https://olusoladavid.github.io/my-diary/UI/
+Live Client: https://olusoladavid.github.io/my-diary-client
 
 ## License
 

diff --git a/server/docs.yaml b/server/docs.yaml
@@ -70,12 +70,16 @@ paths:
           examples:
             application/json:
               error:
-                message:
-                  - location: body
-                    param: email
-                    value: johnnybravo
-                    msg: Your email is invalid
-
+                  - param: email
+                    message: Your email is invalid
+                  - param: password
+                    message: Your password should contain minimum of 5 characters
+        500:
+          description: "Server Error"
+          examples:
+            application/json:
+              error:
+                message: An error occurred on the server
   /auth/login:
     post:
       tags:
@@ -116,11 +120,16 @@ paths:
           examples:
             application/json:
               error:
-                message:
-                  - location: body
-                    param: email
-                    value: johnnybravo
-                    msg: Your email is invalid
+                  - param: email
+                    message: Your email is invalid
+                  - param: password
+                    message: Your password should contain minimum of 5 characters
+        500:
+          description: "Server Error"
+          examples:
+            application/json:
+              error:
+                message: An error occurred on the server
 
   /profile:
     get:
@@ -137,16 +146,76 @@ paths:
           description: "Successful fetched user info"
           examples:
             application/json:
-              email: 'someone@gmail.com'
-              entriesCount: 5
+              email: john.dave@gmail.com
+              entries_count: 35
+              fav_count: 8
+              created_on: '2018-08-17T23:58:13.698Z'
+              push_sub: {}
+              reminder_set: true
         401:
           description: "Authorization error"
           examples:
             application/json:
               error:
                 message:
                   "Authorization failed. Please provide a token"
-
+        500:
+          description: "Server Error"
+          examples:
+            application/json:
+              error:
+                message: An error occurred on the server
+    put:
+      tags:
+      - "User"
+      summary: "Update user profile and preferences"
+      description: "This endpoint updates the user's profile amd sets their reminder preferences"
+      consumes:
+      - "application/json"
+      - "application/x-www-form-urlencoded"
+      produces:
+      - "application/json"
+      parameters:
+      - in: "formData"
+        name: "push_sub"
+        description: "The push subscription object"
+        required: false
+        type: string
+      - in: "formData"
+        name: "reminder_set"
+        description: "Boolean indicating whether reminder is set or not"
+        required: false
+        type: string
+      security:
+      -  Bearer: []
+      responses:
+        204:
+          description: "Successfully updated user profile"
+          examples:
+            application/json:
+              No content
+        400:
+          description: "Bad request. Invalid credentials or data"
+          examples:
+            application/json:
+              error:
+                  - param: push_sub
+                    message: Push Subscription should be JSON
+                  - param: reminder_set
+                    message: Reminder preference should be boolean
+        401:
+          description: "Authorization error"
+          examples:
+            application/json:
+              error:
+                message:
+                  "Authorization failed. Please provide a token"
+        500:
+          description: "Server Error"
+          examples:
+            application/json:
+              error:
+                message: An error occurred on the server
   /entries:
     get:
       tags:
@@ -156,6 +225,11 @@ paths:
       produces:
       - "application/json"
       parameters:
+      - in: "query"
+        name: "filter"
+        description: "The entries that have a particular property which is the value of the filter"
+        required: false
+        type: string
       - in: "query"
         name: "limit"
         description: "The maximum number of entries to return for each request"
@@ -189,14 +263,20 @@ paths:
               meta:
                 limit: 20
                 page: 0
+                count: 2
         401:
           description: "Authorization error"
           examples:
             application/json:
               error:
                 message:
                   "Authorization failed. Please provide a token"
-
+        500:
+          description: "Server Error"
+          examples:
+            application/json:
+              error:
+                message: An error occurred on the server
     post:
       tags:
       - "Entries"
@@ -247,12 +327,16 @@ paths:
           examples:
             application/json:
               error:
-                message:
-                  - location: body
-                    param: title
-                    value: ''
-                    msg: Title should not be empty
-
+                  - param: title
+                    message: Title should not be empty
+                  - param: content
+                    message: Content should not be empty
+        500:
+          description: "Server Error"
+          examples:
+            application/json:
+              error:
+                message: An error occurred on the server
   /entries/{id}:
     get:
       tags:
@@ -291,8 +375,13 @@ paths:
             application/json:
               error:
                 message:
-                  "Entry does not exist"
-
+                  "Entry not found"
+        500:
+          description: "Server Error"
+          examples:
+            application/json:
+              error:
+                message: An error occurred on the server
     put:
       tags:
       - "Entries"
@@ -335,30 +424,35 @@ paths:
               content: 'It was an eventful summer. A week characterized by the nuances of IO conference...'
               is_favorite: true
               created_on: '2018-08-02T10:33:49.297Z'
+        400:
+          description: "Bad request. Invalid credentials or data"
+          examples:
+            application/json:
+              error:
+                  - param: title
+                    message: Title should not be empty
+                  - param: content
+                    message: Content should not be empty
         401:
           description: "Authorization error"
           examples:
             application/json:
               error:
                 message:
                   "Authorization failed. Please provide a token"
-        404:
-          description: "Resource not found"
+        403:
+          description: "Cannot update entry 24 hours or more after it was created"
           examples:
             application/json:
               error:
                 message:
-                  "Entry doees not exist"    
-        400:
-          description: "Bad request. Invalid entry data"
+                  "Cannot update entry after 24 hours"
+        500:
+          description: "Server Error"
           examples:
             application/json:
               error:
-                message:
-                  - location: body
-                    param: is_favorite
-                    value: ''
-                    msg: Entry should either be favorited or not (boolean)
+                message: An error occurred on the server
 
     delete:
       tags:
@@ -390,4 +484,10 @@ paths:
             application/json:
               error:
                 message:
-                  "Entry not found"
+                  "Entry not found"
+        500:
+          description: "Server Error"
+          examples:
+            application/json:
+              error:
+                message: An error occurred on the server
diff --git a/server/utils/validate.js b/server/utils/validate.js
@@ -97,7 +97,7 @@ validate.updateProfile = [
     .optional(),
   body('reminder_set')
     .isBoolean()
-    .withMessage('Email reminder preference should be boolean')
+    .withMessage('Reminder preference should be boolean')
     .optional(),
 ];
 
@@ -117,7 +117,7 @@ validate.getEntries = [
     .isEmpty()
     .withMessage('Filter parameter should not be empty')
     .isIn(['favs'])
-    .withMessage('Filter paramter value is invalid')
+    .withMessage('Filter parameter value is invalid')
     .optional(),
 ];