Merge pull request #5815 from Atry/board-rest-api-doc

feat: enhance API documentation and add board-related endpoints
This commit is contained in:
Lauri Ojansivu 2025-06-26 01:09:42 +03:00 committed by GitHub
commit 9b24d644a4
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
3 changed files with 855 additions and 5 deletions

View file

@ -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

View file

@ -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

View file

@ -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
/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