From ff467402c0c24981078f1f8e2b92b26b0d67d00a Mon Sep 17 00:00:00 2001
From: Benjamin Tissoires <benjamin.tissoires@redhat.com>
Date: Fri, 26 Oct 2018 07:27:24 +0200
Subject: RESTAPI: Add some JSDoc

So we can have a decent REST API documentation generated.
---
 models/integrations.js | 99 ++++++++++++++++++++++++++++++++++++++++++++++----
 1 file changed, 92 insertions(+), 7 deletions(-)

(limited to 'models/integrations.js')

diff --git a/models/integrations.js b/models/integrations.js
index 1062b93b..1c473b57 100644
--- a/models/integrations.js
+++ b/models/integrations.js
@@ -1,33 +1,60 @@
 Integrations = new Mongo.Collection('integrations');
 
+/**
+ * Integration with third-party applications
+ */
 Integrations.attachSchema(new SimpleSchema({
   enabled: {
+    /**
+     * is the integration enabled?
+     */
     type: Boolean,
     defaultValue: true,
   },
   title: {
+    /**
+     * name of the integration
+     */
     type: String,
     optional: true,
   },
   type: {
+    /**
+     * type of the integratation (Default to 'outgoing-webhooks')
+     */
     type: String,
     defaultValue: 'outgoing-webhooks',
   },
   activities: {
+    /**
+     * activities the integration gets triggered (list)
+     */
     type: [String],
     defaultValue: ['all'],
   },
   url: { // URL validation regex (https://mathiasbynens.be/demo/url-regex)
+    /**
+     * URL validation regex (https://mathiasbynens.be/demo/url-regex)
+     */
     type: String,
   },
   token: {
+    /**
+     * token of the integration
+     */
     type: String,
     optional: true,
   },
   boardId: {
+    /**
+     * Board ID of the integration
+     */
     type: String,
   },
   createdAt: {
+    /**
+     * Creation date of the integration
+     */
     type: Date,
     denyUpdate: false,
     autoValue() { // eslint-disable-line consistent-return
@@ -39,6 +66,9 @@ Integrations.attachSchema(new SimpleSchema({
     },
   },
   userId: {
+    /**
+     * user ID who created the interation
+     */
     type: String,
   },
 }));
@@ -58,7 +88,13 @@ Integrations.allow({
 
 //INTEGRATIONS REST API
 if (Meteor.isServer) {
-  // Get all integrations in board
+  /**
+   * @operation get_all_integrations
+   * @summary Get all integrations in board
+   *
+   * @param {string} boardId the board ID
+   * @return_type [Integrations]
+   */
   JsonRoutes.add('GET', '/api/boards/:boardId/integrations', function(req, res) {
     try {
       const paramBoardId = req.params.boardId;
@@ -78,7 +114,14 @@ if (Meteor.isServer) {
     }
   });
 
-  // Get a single integration in board
+  /**
+   * @operation get_integration
+   * @summary Get a single integration in board
+   *
+   * @param {string} boardId the board ID
+   * @param {string} intId the integration ID
+   * @return_type Integrations
+   */
   JsonRoutes.add('GET', '/api/boards/:boardId/integrations/:intId', function(req, res) {
     try {
       const paramBoardId = req.params.boardId;
@@ -98,7 +141,14 @@ if (Meteor.isServer) {
     }
   });
 
-  // Create a new integration
+  /**
+   * @operation new_integration
+   * @summary Create a new integration
+   *
+   * @param {string} boardId the board ID
+   * @param {string} url the URL of the integration
+   * @return_type {_id: string}
+   */
   JsonRoutes.add('POST', '/api/boards/:boardId/integrations', function(req, res) {
     try {
       const paramBoardId = req.params.boardId;
@@ -125,7 +175,19 @@ if (Meteor.isServer) {
     }
   });
 
-  // Edit integration data
+  /**
+   * @operation edit_integration
+   * @summary Edit integration data
+   *
+   * @param {string} boardId the board ID
+   * @param {string} intId the integration ID
+   * @param {string} [enabled] is the integration enabled?
+   * @param {string} [title] new name of the integration
+   * @param {string} [url] new URL of the integration
+   * @param {string} [token] new token of the integration
+   * @param {string} [activities] new list of activities of the integration
+   * @return_type {_id: string}
+   */
   JsonRoutes.add('PUT', '/api/boards/:boardId/integrations/:intId', function (req, res) {
     try {
       const paramBoardId = req.params.boardId;
@@ -173,7 +235,15 @@ if (Meteor.isServer) {
     }
   });
 
-  // Delete subscribed activities
+  /**
+   * @operation delete_integration_activities
+   * @summary Delete subscribed activities
+   *
+   * @param {string} boardId the board ID
+   * @param {string} intId the integration ID
+   * @param {string} newActivities the activities to remove from the integration
+   * @return_type Integrations
+   */
   JsonRoutes.add('DELETE', '/api/boards/:boardId/integrations/:intId/activities', function (req, res) {
     try {
       const paramBoardId = req.params.boardId;
@@ -197,7 +267,15 @@ if (Meteor.isServer) {
     }
   });
 
-  // Add subscribed activities
+  /**
+   * @operation new_integration_activities
+   * @summary Add subscribed activities
+   *
+   * @param {string} boardId the board ID
+   * @param {string} intId the integration ID
+   * @param {string} newActivities the activities to add to the integration
+   * @return_type Integrations
+   */
   JsonRoutes.add('POST', '/api/boards/:boardId/integrations/:intId/activities', function (req, res) {
     try {
       const paramBoardId = req.params.boardId;
@@ -221,7 +299,14 @@ if (Meteor.isServer) {
     }
   });
 
-  // Delete integration
+  /**
+   * @operation delete_integration
+   * @summary Delete integration
+   *
+   * @param {string} boardId the board ID
+   * @param {string} intId the integration ID
+   * @return_type {_id: string}
+   */
   JsonRoutes.add('DELETE', '/api/boards/:boardId/integrations/:intId', function (req, res) {
     try {
       const paramBoardId = req.params.boardId;
-- 
cgit v1.2.3-1-g7c22