diff options
author | Benjamin Tissoires <benjamin.tissoires@redhat.com> | 2018-10-26 07:27:24 +0200 |
---|---|---|
committer | Benjamin Tissoires <benjamin.tissoires@redhat.com> | 2019-01-18 17:02:56 +0100 |
commit | ff467402c0c24981078f1f8e2b92b26b0d67d00a (patch) | |
tree | 289b4647e571f7896172028068b2bd130cbfa757 /models/boards.js | |
parent | 49d3eb5a3f21fad1eb2952eb3da2f93c5c5d6272 (diff) | |
download | wekan-ff467402c0c24981078f1f8e2b92b26b0d67d00a.tar.gz wekan-ff467402c0c24981078f1f8e2b92b26b0d67d00a.tar.bz2 wekan-ff467402c0c24981078f1f8e2b92b26b0d67d00a.zip |
RESTAPI: Add some JSDoc
So we can have a decent REST API documentation generated.
Diffstat (limited to 'models/boards.js')
-rw-r--r-- | models/boards.js | 176 |
1 files changed, 176 insertions, 0 deletions
diff --git a/models/boards.js b/models/boards.js index db3b1149..99480ca7 100644 --- a/models/boards.js +++ b/models/boards.js @@ -1,10 +1,19 @@ Boards = new Mongo.Collection('boards'); +/** + * This is a Board. + */ Boards.attachSchema(new SimpleSchema({ title: { + /** + * The title of the board + */ type: String, }, slug: { + /** + * The title slugified. + */ type: String, autoValue() { // eslint-disable-line consistent-return // XXX We need to improve slug management. Only the id should be necessary @@ -24,6 +33,9 @@ Boards.attachSchema(new SimpleSchema({ }, }, archived: { + /** + * Is the board archived? + */ type: Boolean, autoValue() { // eslint-disable-line consistent-return if (this.isInsert && !this.isSet) { @@ -32,6 +44,9 @@ Boards.attachSchema(new SimpleSchema({ }, }, createdAt: { + /** + * Creation time of the board + */ type: Date, autoValue() { // eslint-disable-line consistent-return if (this.isInsert) { @@ -43,6 +58,9 @@ Boards.attachSchema(new SimpleSchema({ }, // XXX Inconsistent field naming modifiedAt: { + /** + * Last modification time of the board + */ type: Date, optional: true, autoValue() { // eslint-disable-line consistent-return @@ -55,6 +73,9 @@ Boards.attachSchema(new SimpleSchema({ }, // De-normalized number of users that have starred this board stars: { + /** + * How many stars the board has + */ type: Number, autoValue() { // eslint-disable-line consistent-return if (this.isInsert) { @@ -64,6 +85,9 @@ Boards.attachSchema(new SimpleSchema({ }, // De-normalized label system 'labels': { + /** + * List of labels attached to a board + */ type: [Object], autoValue() { // eslint-disable-line consistent-return if (this.isInsert && !this.isSet) { @@ -78,6 +102,9 @@ Boards.attachSchema(new SimpleSchema({ }, }, 'labels.$._id': { + /** + * Unique id of a label + */ // We don't specify that this field must be unique in the board because that // will cause performance penalties and is not necessary since this field is // always set on the server. @@ -86,10 +113,22 @@ Boards.attachSchema(new SimpleSchema({ type: String, }, 'labels.$.name': { + /** + * Name of a label + */ type: String, optional: true, }, 'labels.$.color': { + /** + * color of a label. + * + * Can be amongst `green`, `yellow`, `orange`, `red`, `purple`, + * `blue`, `sky`, `lime`, `pink`, `black`, + * `silver`, `peachpuff`, `crimson`, `plum`, `darkgreen`, + * `slateblue`, `magenta`, `gold`, `navy`, `gray`, + * `saddlebrown`, `paleturquoise`, `mistyrose`, `indigo` + */ type: String, allowedValues: [ 'green', 'yellow', 'orange', 'red', 'purple', @@ -103,6 +142,9 @@ Boards.attachSchema(new SimpleSchema({ // documents like de-normalized meta-data (the date the member joined the // board, the number of contributions, etc.). 'members': { + /** + * List of members of a board + */ type: [Object], autoValue() { // eslint-disable-line consistent-return if (this.isInsert && !this.isSet) { @@ -117,27 +159,48 @@ Boards.attachSchema(new SimpleSchema({ }, }, 'members.$.userId': { + /** + * The uniq ID of the member + */ type: String, }, 'members.$.isAdmin': { + /** + * Is the member an admin of the board? + */ type: Boolean, }, 'members.$.isActive': { + /** + * Is the member active? + */ type: Boolean, }, 'members.$.isNoComments': { + /** + * Is the member not allowed to make comments + */ type: Boolean, optional: true, }, 'members.$.isCommentOnly': { + /** + * Is the member only allowed to comment on the board + */ type: Boolean, optional: true, }, permission: { + /** + * visibility of the board + */ type: String, allowedValues: ['public', 'private'], }, color: { + /** + * The color of the board. + */ type: String, allowedValues: [ 'belize', @@ -154,24 +217,45 @@ Boards.attachSchema(new SimpleSchema({ }, }, description: { + /** + * The description of the board + */ type: String, optional: true, }, subtasksDefaultBoardId: { + /** + * The default board ID assigned to subtasks. + */ type: String, optional: true, defaultValue: null, }, subtasksDefaultListId: { + /** + * The default List ID assigned to subtasks. + */ type: String, optional: true, defaultValue: null, }, allowsSubtasks: { + /** + * Does the board allows subtasks? + */ type: Boolean, defaultValue: true, }, presentParentTask: { + /** + * Controls how to present the parent task: + * + * - `prefix-with-full-path`: add a prefix with the full path + * - `prefix-with-parent`: add a prefisx with the parent name + * - `subtext-with-full-path`: add a subtext with the full path + * - `subtext-with-parent`: add a subtext with the parent name + * - `no-parent`: does not show the parent at all + */ type: String, allowedValues: [ 'prefix-with-full-path', @@ -184,23 +268,38 @@ Boards.attachSchema(new SimpleSchema({ defaultValue: 'no-parent', }, startAt: { + /** + * Starting date of the board. + */ type: Date, optional: true, }, dueAt: { + /** + * Due date of the board. + */ type: Date, optional: true, }, endAt: { + /** + * End date of the board. + */ type: Date, optional: true, }, spentTime: { + /** + * Time spent in the board. + */ type: Number, decimal: true, optional: true, }, isOvertime: { + /** + * Is the board overtimed? + */ type: Boolean, defaultValue: false, optional: true, @@ -774,6 +873,14 @@ if (Meteor.isServer) { //BOARDS REST API if (Meteor.isServer) { + /** + * @operation get_boards_from_user + * @summary Get all boards attached to a user + * + * @param {string} userId the ID of the user to retrieve the data + * @return_type [{_id: string, + title: string}] + */ JsonRoutes.add('GET', '/api/users/:userId/boards', function (req, res) { try { Authentication.checkLoggedIn(req.userId); @@ -804,6 +911,13 @@ if (Meteor.isServer) { } }); + /** + * @operation get_public_boards + * @summary Get all public boards + * + * @return_type [{_id: string, + title: string}] + */ JsonRoutes.add('GET', '/api/boards', function (req, res) { try { Authentication.checkUserId(req.userId); @@ -825,6 +939,13 @@ if (Meteor.isServer) { } }); + /** + * @operation get_board + * @summary Get the board with that particular ID + * + * @param {string} boardId the ID of the board to retrieve the data + * @return_type Boards + */ JsonRoutes.add('GET', '/api/boards/:boardId', function (req, res) { try { const id = req.params.boardId; @@ -843,6 +964,31 @@ if (Meteor.isServer) { } }); + /** + * @operation new_board + * @summary Create a board + * + * @description This allows to create a board. + * + * The color has to be chosen between `belize`, `nephritis`, `pomegranate`, + * `pumpkin`, `wisteria`, `midnight`: + * + * <img src="https://wekan.github.io/board-colors.png" width="40%" alt="Wekan logo" /> + * + * @param {string} title the new title of the board + * @param {string} owner "ABCDE12345" <= User ID in Wekan. + * (Not username or email) + * @param {boolean} [isAdmin] is the owner an admin of the board (default true) + * @param {boolean} [isActive] is the board active (default true) + * @param {boolean} [isNoComments] disable comments (default false) + * @param {boolean} [isCommentOnly] only enable comments (default false) + * @param {string} [permission] "private" board <== Set to "public" if you + * want public Wekan board + * @param {string} [color] the color of the board + * + * @return_type {_id: string, + defaultSwimlaneId: string} + */ JsonRoutes.add('POST', '/api/boards', function (req, res) { try { Authentication.checkUserId(req.userId); @@ -880,6 +1026,12 @@ if (Meteor.isServer) { } }); + /** + * @operation delete_board + * @summary Delete a board + * + * @param {string} boardId the ID of the board + */ JsonRoutes.add('DELETE', '/api/boards/:boardId', function (req, res) { try { Authentication.checkUserId(req.userId); @@ -900,6 +1052,19 @@ if (Meteor.isServer) { } }); + /** + * @operation add_board_label + * @summary Add a label to a board + * + * @description If the board doesn't have the name/color label, this function + * adds the label to the board. + * + * @param {string} boardId the board + * @param {string} color the color of the new label + * @param {string} name the name of the new label + * + * @return_type string + */ JsonRoutes.add('PUT', '/api/boards/:boardId/labels', function (req, res) { Authentication.checkUserId(req.userId); const id = req.params.boardId; @@ -929,6 +1094,17 @@ if (Meteor.isServer) { } }); + /** + * @operation set_board_member_permission + * @tag Users + * @summary Change the permission of a member of a board + * + * @param {string} boardId the ID of the board that we are changing + * @param {string} memberId the ID of the user to change permissions + * @param {boolean} isAdmin admin capability + * @param {boolean} isNoComments NoComments capability + * @param {boolean} isCommentOnly CommentsOnly capability + */ JsonRoutes.add('POST', '/api/boards/:boardId/members/:memberId', function (req, res) { try { const boardId = req.params.boardId; |