From ff467402c0c24981078f1f8e2b92b26b0d67d00a Mon Sep 17 00:00:00 2001 From: Benjamin Tissoires 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/cards.js | 169 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 169 insertions(+) (limited to 'models/cards.js') diff --git a/models/cards.js b/models/cards.js index 7b05e4b5..aa0bf93e 100644 --- a/models/cards.js +++ b/models/cards.js @@ -5,11 +5,17 @@ Cards = new Mongo.Collection('cards'); // of comments just to display the number of them in the board view. Cards.attachSchema(new SimpleSchema({ title: { + /** + * the title of the card + */ type: String, optional: true, defaultValue: '', }, archived: { + /** + * is the card archived + */ type: Boolean, autoValue() { // eslint-disable-line consistent-return if (this.isInsert && !this.isSet) { @@ -18,33 +24,51 @@ Cards.attachSchema(new SimpleSchema({ }, }, parentId: { + /** + * ID of the parent card + */ type: String, optional: true, defaultValue: '', }, listId: { + /** + * List ID where the card is + */ type: String, optional: true, defaultValue: '', }, swimlaneId: { + /** + * Swimlane ID where the card is + */ type: String, }, // The system could work without this `boardId` information (we could deduce // the board identifier from the card), but it would make the system more // difficult to manage and less efficient. boardId: { + /** + * Board ID of the card + */ type: String, optional: true, defaultValue: '', }, coverId: { + /** + * Cover ID of the card + */ type: String, optional: true, defaultValue: '', }, createdAt: { + /** + * creation date + */ type: Date, autoValue() { // eslint-disable-line consistent-return if (this.isInsert) { @@ -55,6 +79,9 @@ Cards.attachSchema(new SimpleSchema({ }, }, customFields: { + /** + * list of custom fields + */ type: [Object], optional: true, defaultValue: [], @@ -62,11 +89,17 @@ Cards.attachSchema(new SimpleSchema({ 'customFields.$': { type: new SimpleSchema({ _id: { + /** + * the ID of the related custom field + */ type: String, optional: true, defaultValue: '', }, value: { + /** + * value attached to the custom field + */ type: Match.OneOf(String, Number, Boolean, Date), optional: true, defaultValue: '', @@ -74,59 +107,95 @@ Cards.attachSchema(new SimpleSchema({ }), }, dateLastActivity: { + /** + * Date of last activity + */ type: Date, autoValue() { return new Date(); }, }, description: { + /** + * description of the card + */ type: String, optional: true, defaultValue: '', }, requestedBy: { + /** + * who requested the card (ID of the user) + */ type: String, optional: true, defaultValue: '', }, assignedBy: { + /** + * who assigned the card (ID of the user) + */ type: String, optional: true, defaultValue: '', }, labelIds: { + /** + * list of labels ID the card has + */ type: [String], optional: true, defaultValue: [], }, members: { + /** + * list of members (user IDs) + */ type: [String], optional: true, defaultValue: [], }, receivedAt: { + /** + * Date the card was received + */ type: Date, optional: true, }, startAt: { + /** + * Date the card was started to be worked on + */ type: Date, optional: true, }, dueAt: { + /** + * Date the card is due + */ type: Date, optional: true, }, endAt: { + /** + * Date the card ended + */ type: Date, optional: true, }, spentTime: { + /** + * How much time has been spent on this + */ type: Number, decimal: true, optional: true, defaultValue: 0, }, isOvertime: { + /** + * is the card over time? + */ type: Boolean, defaultValue: false, optional: true, @@ -134,6 +203,9 @@ Cards.attachSchema(new SimpleSchema({ // XXX Should probably be called `authorId`. Is it even needed since we have // the `members` field? userId: { + /** + * user ID of the author of the card + */ type: String, autoValue() { // eslint-disable-line consistent-return if (this.isInsert && !this.isSet) { @@ -142,21 +214,33 @@ Cards.attachSchema(new SimpleSchema({ }, }, sort: { + /** + * Sort value + */ type: Number, decimal: true, defaultValue: '', }, subtaskSort: { + /** + * subtask sort value + */ type: Number, decimal: true, defaultValue: -1, optional: true, }, type: { + /** + * type of the card + */ type: String, defaultValue: '', }, linkedId: { + /** + * ID of the linked card + */ type: String, optional: true, defaultValue: '', @@ -1309,6 +1393,17 @@ if (Meteor.isServer) { } //SWIMLANES REST API if (Meteor.isServer) { + /** + * @operation get_swimlane_cards + * @summary get all cards attached to a swimlane + * + * @param {string} boardId the board ID + * @param {string} swimlaneId the swimlane ID + * @return_type [{_id: string, + * title: string, + * description: string, + * listId: string}] + */ JsonRoutes.add('GET', '/api/boards/:boardId/swimlanes/:swimlaneId/cards', function(req, res) { const paramBoardId = req.params.boardId; const paramSwimlaneId = req.params.swimlaneId; @@ -1332,6 +1427,16 @@ if (Meteor.isServer) { } //LISTS REST API if (Meteor.isServer) { + /** + * @operation get_all_cards + * @summary get all cards attached to a list + * + * @param {string} boardId the board ID + * @param {string} listId the list ID + * @return_type [{_id: string, + * title: string, + * description: string}] + */ JsonRoutes.add('GET', '/api/boards/:boardId/lists/:listId/cards', function(req, res) { const paramBoardId = req.params.boardId; const paramListId = req.params.listId; @@ -1352,6 +1457,15 @@ if (Meteor.isServer) { }); }); + /** + * @operation get_card + * @summary get a card + * + * @param {string} boardId the board ID + * @param {string} listId the list ID of the card + * @param {string} cardId the card ID + * @return_type Cards + */ JsonRoutes.add('GET', '/api/boards/:boardId/lists/:listId/cards/:cardId', function(req, res) { const paramBoardId = req.params.boardId; const paramListId = req.params.listId; @@ -1368,6 +1482,19 @@ if (Meteor.isServer) { }); }); + /** + * @operation new_card + * @summary creates a new card + * + * @param {string} boardId the board ID of the new card + * @param {string} listId the list ID of the new card + * @param {string} authorID the user ID of the person owning the card + * @param {string} title the title of the new card + * @param {string} description the description of the new card + * @param {string} swimlaneId the swimlane ID of the new card + * @param {string} [members] the member IDs list of the new card + * @return_type {_id: string} + */ JsonRoutes.add('POST', '/api/boards/:boardId/lists/:listId/cards', function(req, res) { Authentication.checkUserId(req.userId); const paramBoardId = req.params.boardId; @@ -1406,6 +1533,36 @@ if (Meteor.isServer) { } }); + /* + * Note for the JSDoc: + * 'list' will be interpreted as the path parameter + * 'listID' will be interpreted as the body parameter + */ + /** + * @operation edit_card + * @summary edit fields in a card + * + * @param {string} boardId the board ID of the card + * @param {string} list the list ID of the card + * @param {string} cardId the ID of the card + * @param {string} [title] the new title of the card + * @param {string} [listId] the new list ID of the card (move operation) + * @param {string} [description] the new description of the card + * @param {string} [authorId] change the owner of the card + * @param {string} [labelIds] the new list of label IDs attached to the card + * @param {string} [swimlaneId] the new swimlane ID of the card + * @param {string} [members] the new list of member IDs attached to the card + * @param {string} [requestedBy] the new requestedBy field of the card + * @param {string} [assignedBy] the new assignedBy field of the card + * @param {string} [receivedAt] the new receivedAt field of the card + * @param {string} [assignBy] the new assignBy field of the card + * @param {string} [startAt] the new startAt field of the card + * @param {string} [dueAt] the new dueAt field of the card + * @param {string} [endAt] the new endAt field of the card + * @param {string} [spentTime] the new spentTime field of the card + * @param {boolean} [isOverTime] the new isOverTime field of the card + * @param {string} [customFields] the new customFields value of the card + */ JsonRoutes.add('PUT', '/api/boards/:boardId/lists/:listId/cards/:cardId', function(req, res) { Authentication.checkUserId(req.userId); const paramBoardId = req.params.boardId; @@ -1551,6 +1708,18 @@ if (Meteor.isServer) { }); }); + /** + * @operation delete_card + * @summary Delete a card from a board + * + * @description This operation **deletes** a card, and therefore the card + * is not put in the recycle bin. + * + * @param {string} boardId the board ID of the card + * @param {string} list the list ID of the card + * @param {string} cardId the ID of the card + * @return_type {_id: string} + */ JsonRoutes.add('DELETE', '/api/boards/:boardId/lists/:listId/cards/:cardId', function(req, res) { Authentication.checkUserId(req.userId); const paramBoardId = req.params.boardId; -- cgit v1.2.3-1-g7c22