feat: enhance API documentation and add board-related endpoints

Previously, boards.js contains a `?.` operator, which is not supported by esprima, therefore boards.js is skipped.

This PR fixes the API generation for borads.js by removing `?.`.

See https://github.com/jquery/esprima/issues/2112

models/boards.js

@@ -1760,7 +1760,7 @@ if (Meteor.isServer) {
       ).sort();
     },
     setAllBoardsHideActivities() {
-      if (ReactiveCache.getCurrentUser()?.isAdmin) {
+      if ((ReactiveCache.getCurrentUser() || {}).isAdmin) {
         Boards.update(
           {
             showActivities: true
@@ -2001,8 +2001,8 @@ if (Meteor.isServer) {
    *
    * @param {string} userId the ID of the user to retrieve the data
    * @return_type [{_id: string,
-                    title: string}]
-                    */
+   *                title: string}]
+   */
   JsonRoutes.add('GET', '/api/users/:userId/boards', function(req, res) {
     try {
       Authentication.checkLoggedIn(req.userId);
@@ -2236,7 +2236,7 @@ if (Meteor.isServer) {
       });
     }
   });
-  
+
   /**
    * @operation add_board_label
    * @summary Add a label to a board

openapi/README.md

@@ -13,7 +13,7 @@ the REST API of Wekan and exports it under the OpenAPI 2.0 specification
 
 ### calling the tool
 
-    python3 generate_openapi.py --release v1.65 > ../public/wekan_api.yml
+    python3 generate_openapi.py --release v7.92 > ../public/api/wekan.yml
 
 ## Generating docs
 Now that we have the OpenAPI, it's easy enough to convert the YAML file into some nice Markdown with

public/api/wekan.yml

@@ -150,6 +150,204 @@ paths:
           description: |
             Error in registration
 
+  /api/boards:
+    get:
+      operationId: get_public_boards
+      summary: Get all public boards
+      tags:
+        - Boards
+      produces:
+        - application/json
+      security:
+          - UserSecurity: []
+      responses:
+        '200':
+          description: |-
+            200 response
+          schema:
+            type: array
+            items:
+              type: object
+              properties:
+                _id:
+                  type: string
+                title:
+                  type: string
+    post:
+      operationId: 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`, `moderatepink`, `strongcyan`,
+         `limegreen`, `midnight`, `dark`, `relax`, `corteza`:
+
+         <img src="https://wekan.github.io/board-colors.png" width="40%" alt="Wekan logo" />
+      tags:
+        - Boards
+      consumes:
+        - multipart/form-data
+        - application/json
+      parameters:
+        - name: title
+          in: formData
+          description: |
+            the new title of the board
+          type: string
+          required: true
+        - name: owner
+          in: formData
+          description: |
+            "ABCDE12345" <= User ID in Wekan.
+                 (Not username or email)
+          type: string
+          required: true
+        - name: isAdmin
+          in: formData
+          description: |
+            is the owner an admin of the board (default true)
+          type: boolean
+          required: false
+        - name: isActive
+          in: formData
+          description: |
+            is the board active (default true)
+          type: boolean
+          required: false
+        - name: isNoComments
+          in: formData
+          description: |
+            disable comments (default false)
+          type: boolean
+          required: false
+        - name: isCommentOnly
+          in: formData
+          description: |
+            only enable comments (default false)
+          type: boolean
+          required: false
+        - name: isWorker
+          in: formData
+          description: |
+            only move cards, assign himself to card and comment (default false)
+          type: boolean
+          required: false
+        - name: permission
+          in: formData
+          description: |
+            "private" board <== Set to "public" if you
+                 want public Wekan board
+          type: string
+          required: false
+        - name: color
+          in: formData
+          description: |
+            the color of the board
+          type: string
+          required: false
+      produces:
+        - application/json
+      security:
+          - UserSecurity: []
+      responses:
+        '200':
+          description: |-
+            200 response
+          schema:
+            type: object
+            properties:
+              _id:
+                type: string
+              defaultSwimlaneId:
+                type: string
+  /api/boards/{board}:
+    get:
+      operationId: get_board
+      summary: Get the board with that particular ID
+      tags:
+        - Boards
+      parameters:
+        - name: board
+          in: path
+          description: |
+            the ID of the board to retrieve the data
+          type: string
+          required: true
+      produces:
+        - application/json
+      security:
+          - UserSecurity: []
+      responses:
+        '200':
+          description: |-
+            200 response
+          schema:
+            $ref: "#/definitions/Boards"
+    delete:
+      operationId: delete_board
+      summary: Delete a board
+      tags:
+        - Boards
+      parameters:
+        - name: board
+          in: path
+          description: |
+            the ID of the board
+          type: string
+          required: true
+      produces:
+        - application/json
+      security:
+          - UserSecurity: []
+      responses:
+        '200':
+          description: |-
+            200 response
+  /api/boards/{board}/attachments:
+    get:
+      operationId: get_board_attachments
+      summary: Get the list of attachments of a board
+      tags:
+        - Boards
+      parameters:
+        - name: board
+          in: path
+          description: |
+            the board ID
+          type: string
+          required: true
+      produces:
+        - application/json
+      security:
+          - UserSecurity: []
+      responses:
+        '200':
+          description: |-
+            200 response
+          schema:
+            type: array
+            items:
+              type: object
+              properties:
+                attachmentId:
+                  type: string
+                attachmentName:
+                  type: string
+                attachmentType:
+                  type: string
+                url:
+                  type: string
+                urlDownload:
+                  type: string
+                boardId:
+                  type: string
+                swimlaneId:
+                  type: string
+                listId:
+                  type: string
+                cardId:
+                  type: string  
   /api/boards/{board}/attachments/{attachment}/export:
     get:
       operationId: exportJson
@@ -781,6 +979,41 @@ paths:
             properties:
               board_cards_count:
                 type: integer
+  /api/boards/{board}/copy:
+    post:
+      operationId: copy_board
+      summary: Copy a board to a new one
+      description: |
+        If your are board admin or wekan admin, this copies the
+         given board to a new one.
+      tags:
+        - Boards
+      consumes:
+        - multipart/form-data
+        - application/json
+      parameters:
+        - name: title
+          in: formData
+          description: |
+            the title of the new board (default to old one)
+          type: string
+          required: true
+        - name: board
+          in: path
+          description: |
+            the board
+          type: string
+          required: true
+      produces:
+        - application/json
+      security:
+          - UserSecurity: []
+      responses:
+        '200':
+          description: |-
+            200 response
+          schema:
+            type: string
   /api/boards/{board}/custom-fields:
     get:
       operationId: get_all_custom_fields
@@ -1424,6 +1657,41 @@ paths:
             200 response
           schema:
             $ref: "#/definitions/Integrations"
+  /api/boards/{board}/labels:
+    put:
+      operationId: 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.
+      tags:
+        - Boards
+        - Boards
+      consumes:
+        - multipart/form-data
+        - application/json
+      parameters:
+        - name: label
+          in: formData
+          description: the label value
+          type: string
+          required: true
+        - name: board
+          in: path
+          description: |
+            the board
+          type: string
+          required: true
+      produces:
+        - application/json
+      security:
+          - UserSecurity: []
+      responses:
+        '200':
+          description: |-
+            200 response
+          schema:
+            type: string
   /api/boards/{board}/lists:
     get:
       operationId: get_all_lists
@@ -2026,6 +2294,61 @@ paths:
             properties:
               list_cards_count:
                 type: integer
+  /api/boards/{board}/members/{member}:
+    post:
+      operationId: set_board_member_permission
+      summary: Change the permission of a member of a board
+      tags:
+        - Boards
+        - Users
+      consumes:
+        - multipart/form-data
+        - application/json
+      parameters:
+        - name: isAdmin
+          in: formData
+          description: |
+            admin capability
+          type: boolean
+          required: true
+        - name: isNoComments
+          in: formData
+          description: |
+            NoComments capability
+          type: boolean
+          required: true
+        - name: isCommentOnly
+          in: formData
+          description: |
+            CommentsOnly capability
+          type: boolean
+          required: true
+        - name: isWorker
+          in: formData
+          description: |
+            Worker capability
+          type: boolean
+          required: true
+        - name: board
+          in: path
+          description: |
+            the ID of the board that we are changing
+          type: string
+          required: true
+        - name: member
+          in: path
+          description: |
+            the ID of the user to change permissions
+          type: string
+          required: true
+      produces:
+        - application/json
+      security:
+          - UserSecurity: []
+      responses:
+        '200':
+          description: |-
+            200 response
   /api/boards/{board}/swimlanes:
     get:
       operationId: get_all_swimlanes
@@ -2232,7 +2555,534 @@ paths:
                   type: string
                 listId:
                   type: string
-definitions:
+  /api/boards/{board}/title:
+    put:
+      operationId: update_board_title
+      summary: Update the title of a board
+      tags:
+        - Boards
+      consumes:
+        - multipart/form-data
+        - application/json
+      parameters:
+        - name: title
+          in: formData
+          description: |
+            the new title for the board
+          type: string
+          required: true
+        - name: board
+          in: path
+          description: |
+            the ID of the board to update
+          type: string
+          required: true
+      produces:
+        - application/json
+      security:
+          - UserSecurity: []
+      responses:
+        '200':
+          description: |-
+            200 response
+  /api/boards_count:
+    get:
+      operationId: get_boards_count
+      summary: Get public and private boards count
+      tags:
+        - Boards
+      produces:
+        - application/json
+      security:
+          - UserSecurity: []
+      responses:
+        '200':
+          description: |-
+            200 response
+          schema:
+            type: object
+            properties:
+              private:
+                type: integer
+              public:
+                type: integer
+  /api/users/{user}/boards:
+    get:
+      operationId: get_boards_from_user
+      summary: Get all boards attached to a user
+      tags:
+        - Boards
+      parameters:
+        - name: user
+          in: path
+          description: |
+            the ID of the user to retrieve the data
+          type: string
+          required: true
+      produces:
+        - application/json
+      security:
+          - UserSecurity: []
+      responses:
+        '200':
+          description: |-
+            200 response
+          schema:
+            type: array
+            items:
+              type: object
+              properties:
+                _id:
+                  type: string
+                title:
+                  type: string
+definitions:
+  Boards:
+    type: object
+    description:  This is a Board.
+    properties:
+      title:
+        description: |
+           The title of the board
+        type: string
+      slug:
+        description: |
+           The title slugified.
+        type: string
+      archived:
+        description: |
+           Is the board archived?
+        type: boolean
+      archivedAt:
+        description: |
+           Latest archiving time of the board
+        type: string
+        x-nullable: true
+      createdAt:
+        description: |
+           Creation time of the board
+        type: string
+      modifiedAt:
+        description: |
+           Last modification time of the board
+        type: string
+        x-nullable: true
+      stars:
+        description: |
+           How many stars the board has
+        type: number
+      labels:
+        description: |
+           List of labels attached to a board
+        type: array
+        items:
+          $ref: "#/definitions/BoardsLabels"
+        x-nullable: true
+      members:
+        description: |
+           List of members of a board
+        type: array
+        items:
+          $ref: "#/definitions/BoardsMembers"
+      permission:
+        description: |
+           visibility of the board
+        type: string
+        enum:
+          - public
+          - private
+      orgs:
+        description: |
+           the list of organizations that a board belongs to
+        type: array
+        items:
+          $ref: "#/definitions/BoardsOrgs"
+        x-nullable: true
+      teams:
+        description: |
+           the list of teams that a board belongs to
+        type: array
+        items:
+          $ref: "#/definitions/BoardsTeams"
+        x-nullable: true
+      color:
+        description: |
+           The color of the board.
+        type: string
+        enum:
+          - belize
+          - nephritis
+          - pomegranate
+          - pumpkin
+          - wisteria
+          - moderatepink
+          - strongcyan
+          - limegreen
+          - midnight
+          - dark
+          - relax
+          - corteza
+          - clearblue
+          - natural
+          - modern
+          - moderndark
+          - exodark
+          - cleandark
+          - cleanlight
+      backgroundImageURL:
+        description: |
+           The background image URL of the board.
+        type: string
+        x-nullable: true
+      allowsCardCounterList:
+        description: |
+           Show card counter per list
+        type: boolean
+      allowsBoardMemberList:
+        description: |
+           Show board member list
+        type: boolean
+      description:
+        description: |
+           The description of the board
+        type: string
+        x-nullable: true
+      subtasksDefaultBoardId:
+        description: |
+           The default board ID assigned to subtasks.
+        type: string
+        x-nullable: true
+      subtasksDefaultListId:
+        description: |
+           The default List ID assigned to subtasks.
+        type: string
+        x-nullable: true
+      dateSettingsDefaultBoardId:
+        type: string
+        x-nullable: true
+      dateSettingsDefaultListId:
+        type: string
+        x-nullable: true
+      allowsSubtasks:
+        description: |
+           Does the board allows subtasks?
+        type: boolean
+      allowsAttachments:
+        description: |
+           Does the board allows attachments?
+        type: boolean
+      allowsChecklists:
+        description: |
+           Does the board allows checklists?
+        type: boolean
+      allowsComments:
+        description: |
+           Does the board allows comments?
+        type: boolean
+      allowsDescriptionTitle:
+        description: |
+           Does the board allows description title?
+        type: boolean
+      allowsDescriptionText:
+        description: |
+           Does the board allows description text?
+        type: boolean
+      allowsDescriptionTextOnMinicard:
+        description: |
+           Does the board allows description text on minicard?
+        type: boolean
+      allowsCoverAttachmentOnMinicard:
+        description: |
+           Does the board allows cover attachment on minicard?
+        type: boolean
+      allowsBadgeAttachmentOnMinicard:
+        description: |
+           Does the board allows badge attachment on minicard?
+        type: boolean
+      allowsCardSortingByNumberOnMinicard:
+        description: |
+           Does the board allows card sorting by number on minicard?
+        type: boolean
+      allowsCardNumber:
+        description: |
+           Does the board allows card numbers?
+        type: boolean
+      allowsActivities:
+        description: |
+           Does the board allows comments?
+        type: boolean
+      allowsLabels:
+        description: |
+           Does the board allows labels?
+        type: boolean
+      allowsCreator:
+        description: |
+           Does the board allow creator?
+        type: boolean
+      allowsCreatorOnMinicard:
+        description: |
+           Does the board allow creator?
+        type: boolean
+      allowsAssignee:
+        description: |
+           Does the board allows assignee?
+        type: boolean
+      allowsMembers:
+        description: |
+           Does the board allows members?
+        type: boolean
+      allowsRequestedBy:
+        description: |
+           Does the board allows requested by?
+        type: boolean
+      allowsCardSortingByNumber:
+        description: |
+           Does the board allows card sorting by number?
+        type: boolean
+      allowsShowLists:
+        description: |
+           Does the board allows show lists on the card?
+        type: boolean
+      allowsAssignedBy:
+        description: |
+           Does the board allows requested by?
+        type: boolean
+      allowsReceivedDate:
+        description: |
+           Does the board allows received date?
+        type: boolean
+      allowsStartDate:
+        description: |
+           Does the board allows start date?
+        type: boolean
+      allowsEndDate:
+        description: |
+           Does the board allows end date?
+        type: boolean
+      allowsDueDate:
+        description: |
+           Does the board allows due date?
+        type: boolean
+      presentParentTask:
+        description: |
+           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
+        enum:
+          - prefix-with-full-path
+          - prefix-with-parent
+          - subtext-with-full-path
+          - subtext-with-parent
+          - no-parent
+        x-nullable: true
+      receivedAt:
+        description: |
+           Date the card was received
+        type: string
+        x-nullable: true
+      startAt:
+        description: |
+           Starting date of the board.
+        type: string
+        x-nullable: true
+      dueAt:
+        description: |
+           Due date of the board.
+        type: string
+        x-nullable: true
+      endAt:
+        description: |
+           End date of the board.
+        type: string
+        x-nullable: true
+      spentTime:
+        description: |
+           Time spent in the board.
+        type: number
+        x-nullable: true
+      isOvertime:
+        description: |
+           Is the board overtimed?
+        type: boolean
+        x-nullable: true
+      type:
+        description: |
+           The type of board
+           possible values: board, template-board, template-container
+        type: string
+        enum:
+          - board
+          - template-board
+          - template-container
+      sort:
+        description: |
+           Sort value
+        type: number
+      showActivities:
+        type: boolean
+    required:
+      - title
+      - slug
+      - archived
+      - createdAt
+      - stars
+      - members
+      - permission
+      - color
+      - allowsCardCounterList
+      - allowsBoardMemberList
+      - allowsSubtasks
+      - allowsAttachments
+      - allowsChecklists
+      - allowsComments
+      - allowsDescriptionTitle
+      - allowsDescriptionText
+      - allowsDescriptionTextOnMinicard
+      - allowsCoverAttachmentOnMinicard
+      - allowsBadgeAttachmentOnMinicard
+      - allowsCardSortingByNumberOnMinicard
+      - allowsCardNumber
+      - allowsActivities
+      - allowsLabels
+      - allowsCreator
+      - allowsCreatorOnMinicard
+      - allowsAssignee
+      - allowsMembers
+      - allowsRequestedBy
+      - allowsCardSortingByNumber
+      - allowsShowLists
+      - allowsAssignedBy
+      - allowsReceivedDate
+      - allowsStartDate
+      - allowsEndDate
+      - allowsDueDate
+      - type
+      - sort
+      - showActivities
+  BoardsLabels:
+    type: object
+    properties:
+      _id:
+        description: |
+           Unique id of a label
+        type: string
+      name:
+        description: |
+           Name of a label
+        type: string
+      color:
+        description: |
+           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
+        enum:
+          - white
+          - green
+          - yellow
+          - orange
+          - red
+          - purple
+          - blue
+          - sky
+          - lime
+          - pink
+          - black
+          - silver
+          - peachpuff
+          - crimson
+          - plum
+          - darkgreen
+          - slateblue
+          - magenta
+          - gold
+          - navy
+          - gray
+          - saddlebrown
+          - paleturquoise
+          - mistyrose
+          - indigo
+    required:
+      - _id
+      - color
+  BoardsMembers:
+    type: object
+    properties:
+      userId:
+        description: |
+           The uniq ID of the member
+        type: string
+      isAdmin:
+        description: |
+           Is the member an admin of the board?
+        type: boolean
+      isActive:
+        description: |
+           Is the member active?
+        type: boolean
+      isNoComments:
+        description: |
+           Is the member not allowed to make comments
+        type: boolean
+      isCommentOnly:
+        description: |
+           Is the member only allowed to comment on the board
+        type: boolean
+      isWorker:
+        description: |
+           Is the member only allowed to move card, assign himself to card and comment
+        type: boolean
+    required:
+      - userId
+      - isAdmin
+      - isActive
+  BoardsOrgs:
+    type: object
+    properties:
+      orgId:
+        description: |
+           The uniq ID of the organization
+        type: string
+      orgDisplayName:
+        description: |
+           The display name of the organization
+        type: string
+      isActive:
+        description: |
+           Is the organization active?
+        type: boolean
+    required:
+      - orgId
+      - orgDisplayName
+      - isActive
+  BoardsTeams:
+    type: object
+    properties:
+      teamId:
+        description: |
+           The uniq ID of the team
+        type: string
+      teamDisplayName:
+        description: |
+           The display name of the team
+        type: string
+      isActive:
+        description: |
+           Is the team active?
+        type: boolean
+    required:
+      - teamId
+      - teamDisplayName
+      - isActive
   CardComments:
     type: object
     description:  A comment on a card