From 6c206124f54c284cb7692a4cf9d32304abf18e0b Mon Sep 17 00:00:00 2001
From: Roland Bernard <rolbernard@unibz.it>
Date: Fri, 18 Jun 2021 23:20:18 +0200
Subject: [PATCH] Added api documentation for tasks
---
docs/api/projects.md | 14 +-
docs/api/tasks.md | 296 +++++++++++++++++++++++++++++++++++++++++++
docs/api/teams.md | 36 +++---
docs/api/users.md | 2 +-
4 files changed, 322 insertions(+), 26 deletions(-)
diff --git a/docs/api/projects.md b/docs/api/projects.md
index 9fe705f..e9e5251 100644
--- a/docs/api/projects.md
+++ b/docs/api/projects.md
@@ -111,12 +111,12 @@ interface Body {
task: string,
user: string,
started: number,
- finished: number,
+ finished?: number,
}[];
}
```
-### GET `/user/activity?since=X&to=X` [requires authentication]
+### GET `/project/activity?since=X&to=X` [requires authentication]
Get the activity for tasks belonging to the project with the given id, if it is visible to the
currently authenticated user.
@@ -152,7 +152,7 @@ interface Body {
}
```
-### POST `team` [requires authentication]
+### POST `/project` [requires authentication]
Create a new project with the given data. On successful creation the id of the new projects id will
be returned.
@@ -161,7 +161,7 @@ be returned.
```typescript
interface Body {
- teams: Array<string>;
+ teams: string[];
name: string;
text: string;
color: string;
@@ -178,7 +178,7 @@ interface Body {
}
```
-### PUT `team/:uuid` [requires authentication]
+### PUT `/project/:uuid` [requires authentication]
Update the project with the given id.
@@ -186,8 +186,8 @@ Update the project with the given id.
```typescript
interface Body {
- remove_teams?: Array<string>;
- add_teams?: Array<string>;
+ remove_teams?: string[];
+ add_teams?: string[];
name?: string;
text?: string;
color?: string;
diff --git a/docs/api/tasks.md b/docs/api/tasks.md
index 256eeae..43a0b81 100644
--- a/docs/api/tasks.md
+++ b/docs/api/tasks.md
@@ -1 +1,297 @@
## Tasks
+
+### GET `/task` [requires authentication]
+
+Get all the tasks currently visible to the authenticated user.
+
+#### Response body
+
+```typescript
+interface Body {
+ status: string;
+ tasks: {
+ id: string;
+ project: string;
+ name: string;
+ text: string;
+ icon: string;
+ priority: string;
+ status: string;
+ dependencies: string[];
+ requirements: {
+ role: string;
+ time: number;
+ }[];
+ assigned: {
+ user: string;
+ time: number;
+ finished: boolean;
+ }[];
+ created: number;
+ edited: number;
+ color: string;
+ }[];
+}
+```
+
+### GET `/task/:status` [requires authentication]
+
+Get all the tasks currently visible to the authenticated user that have the given status. Status can
+be any of 'open', 'closed', or 'suspended'.
+
+#### Response body
+
+```typescript
+interface Body {
+ status: string;
+ tasks: {
+ id: string;
+ project: string;
+ name: string;
+ text: string;
+ icon: string;
+ priority: string;
+ status: string;
+ dependencies: string[];
+ requirements: {
+ role: string;
+ time: number;
+ }[];
+ assigned: {
+ user: string;
+ time: number;
+ finished: boolean;
+ }[];
+ created: number;
+ edited: number;
+ color: string;
+ }[];
+}
+```
+
+### GET `/task/possible` [requires authentication]
+
+Get all the tasks currently visible to the authenticated user that are currently open and have no
+open dependencies.
+
+#### Response body
+
+```typescript
+interface Body {
+ status: string;
+ tasks: {
+ id: string;
+ project: string;
+ name: string;
+ text: string;
+ icon: string;
+ priority: string;
+ status: string;
+ dependencies: string[];
+ requirements: {
+ role: string;
+ time: number;
+ }[];
+ assigned: {
+ user: string;
+ time: number;
+ finished: boolean;
+ }[];
+ created: number;
+ edited: number;
+ color: string;
+ }[];
+}
+```
+
+### GET `/task/:uuid` [requires authentication]
+
+Get information about the task with the given id.
+
+#### Response body
+
+```typescript
+interface Body {
+ status: string;
+ task: {
+ id: string;
+ project: string;
+ name: string;
+ text: string;
+ icon: string;
+ priority: string;
+ status: string;
+ dependencies: string[];
+ requirements: {
+ role: string;
+ time: number;
+ }[];
+ assigned: {
+ user: string;
+ time: number;
+ finished: boolean;
+ }[];
+ created: number;
+ edited: number;
+ color: string;
+ };
+}
+```
+
+### GET `/task/:uuid` [requires authentication]
+
+Get information about the task with the given id.
+
+#### Response body
+
+```typescript
+interface Body {
+ status: string;
+ task: {
+ id: string;
+ project: string;
+ name: string;
+ text: string;
+ icon: string;
+ priority: string;
+ status: string;
+ dependencies: string[];
+ requirements: {
+ role: string;
+ time: number;
+ }[];
+ assigned: {
+ user: string;
+ time: number;
+ finished: boolean;
+ }[];
+ created: number;
+ edited: number;
+ color: string;
+ };
+}
+```
+
+### GET `/task/:uuid/comments` [requires authentication]
+
+Get all comments that belong to the task with the given id.
+
+#### Response body
+
+```typescript
+interface Body {
+ status: string;
+ comments: {
+ id: string;
+ task: string;
+ user: string;
+ text: string;
+ created: number;
+ edited: number;
+ }[];
+}
+```
+
+### GET `/task/:uuid/work` [requires authentication]
+
+Get all work done for the task with the given id.
+
+#### Response body
+
+```typescript
+interface Body {
+ status: string;
+ work: {
+ id: string;
+ task: string;
+ user: string;
+ started: number;
+ finished?: number;
+ }[];
+}
+```
+
+### GET `/task/:uuid/assigned` [requires authentication]
+
+Get all users that are assigned to the task with the given id.
+
+#### Response body
+
+```typescript
+interface Body {
+ status: string;
+ assigned: {
+ id: string;
+ username: string;
+ email: string;
+ realname: string;
+ time: number;
+ }[];
+}
+```
+
+### POST `/task` [requires authentication]
+
+Create a new task with the given data. On successful creation the id of the new tasks id will
+be returned.
+
+#### Request body
+
+```typescript
+interface Body {
+ project: string;
+ name: string;
+ text: string;
+ icon: string;
+ priority: string;
+ dependencies: string[];
+ requirements: {
+ role: string;
+ time: number;
+ }[];
+ assigned: {
+ user: string;
+ time: number;
+ finished?: boolean;
+ }[];
+}
+```
+
+#### Response body
+
+```typescript
+interface Body {
+ status: string;
+ id: string;
+}
+```
+
+### PUT `/task/:uuid` [requires authentication]
+
+Update the task with the given id.
+
+#### Request body
+
+```typescript
+interface Body {
+ name?: string;
+ text?: string;
+ icon?: string;
+ priority?: string;
+ status?: string;
+ remove_dependencies?: string[];
+ remove_requirements?: string[];
+ remove_assigned?: string[];
+ add_dependencies?: string[];
+ add_requirements?: {
+ role: string;
+ time: number;
+ }[];
+ add_assigned?: {
+ user: string;
+ time: number;
+ finished?: boolean;
+ }[];
+}
+```
+
diff --git a/docs/api/teams.md b/docs/api/teams.md
index ca5a527..c9a3ed5 100644
--- a/docs/api/teams.md
+++ b/docs/api/teams.md
@@ -1,6 +1,6 @@
## Teams
-### POST `team` [requires authentication]
+### POST `/team` [requires authentication]
Create a new team with the given name. On successful creation the id of the new team will be
returned.
@@ -22,7 +22,7 @@ interface Body {
}
```
-### PUT `team/:uuid` [requires authentication]
+### PUT `/team/:uuid` [requires authentication]
Update the team with the given id.
@@ -34,7 +34,7 @@ interface Body {
}
```
-### GET `team/` [requires authentication]
+### GET `/team/` [requires authentication]
Return all the teams the authenticated user is a member of.
@@ -51,7 +51,7 @@ interface Body {
}
```
-### GET `team/:uuid` [requires authentication]
+### GET `/team/:uuid` [requires authentication]
Return the team with the given id. If the authenticated user is a member of the team, the role will
also be included.
@@ -69,7 +69,7 @@ interface Body {
}
```
-### GET `team/:uuid/members` [requires authentication]
+### GET `/team/:uuid/members` [requires authentication]
Get all the users that are members of the team with the given id.
Only teams that the authenticated user is a member of are visible to this function.
@@ -92,7 +92,7 @@ interface Body {
}
```
-### GET `team/:uuid/roles` [requires authentication]
+### GET `/team/:uuid/roles` [requires authentication]
Get all the roles of the team with the given id.
Only teams that the authenticated user is a member of are visible to this function.
@@ -109,7 +109,7 @@ interface Body {
}
```
-### GET `team/:uuid/projects` [requires authentication]
+### GET `/team/:uuid/projects` [requires authentication]
Get all the projects of the team with the given id.
Only teams that the authenticated user is a member of are visible to this function.
@@ -130,7 +130,7 @@ interface Body {
}
```
-### GET `team/:uuid/work` [requires authentication]
+### GET `/team/:uuid/work` [requires authentication]
Get all the work of members of the team with the given id.
Only teams that the authenticated user is a member of are visible to this function.
@@ -145,12 +145,12 @@ interface Body {
task: string;
user: string;
started: number;
- finished: number;
+ finished?: number;
}[];
}
```
-### GET `team/:uuid/activity` [requires authentication]
+### GET `/team/:uuid/activity` [requires authentication]
Get all the activity of members of the team with the given id.
Only teams that the authenticated user is a member of are visible to this function.
@@ -167,7 +167,7 @@ interface Body {
}
```
-### GET `team/:uuid/completion` [requires authentication]
+### GET `/team/:uuid/completion` [requires authentication]
Get all the completion of all tasks in the projects of the team with the given id.
Only teams that the authenticated user is a member of are visible to this function.
@@ -186,7 +186,7 @@ interface Body {
}
```
-### POST `team/:uuid/roles` [requires authentication]
+### POST `/team/:uuid/roles` [requires authentication]
Create a new role in the team with the given id.
Only teams that the authenticated user is a member of are visible to this function.
@@ -199,7 +199,7 @@ interface Body {
}
```
-### PUT `team/:teamid/roles/:roleid` [requires authentication]
+### PUT `/team/:teamid/roles/:roleid` [requires authentication]
Update the role with the given role id in the team with the given team id.
Only teams that the authenticated user is a member of are visible to this function.
@@ -212,13 +212,13 @@ interface Body {
}
```
-### DELETE `team/:teamid/roles/:roleid` [requires authentication]
+### DELETE `/team/:teamid/roles/:roleid` [requires authentication]
Delete the role with the given role id in the team with the given team id. This request will fail if
any member of the team still has the given role.
Only teams that the authenticated user is a member of are visible to this function.
-### POST `team/:uuid/members` [requires authentication]
+### POST `/team/:uuid/members` [requires authentication]
Add a new members to the team with the given id.
Only teams that the authenticated user is a member of are visible to this function.
@@ -232,7 +232,7 @@ interface Body {
}
```
-### PUT `team/:teamid/members` [requires authentication]
+### PUT `/team/:teamid/members` [requires authentication]
Update the member with the given user id in the team with the given team id.
Only teams that the authenticated user is a member of are visible to this function.
@@ -246,12 +246,12 @@ interface Body {
}
```
-### DELETE `team/:teamid/members/:roleid` [requires authentication]
+### DELETE `/team/:teamid/members/:roleid` [requires authentication]
Remove the member with the given user id in the team with the given team id.
Only teams that the authenticated user is a member of are visible to this function.
-### DELETE `team/:teamid/` [requires authentication]
+### DELETE `/team/:teamid/` [requires authentication]
Cause the authenticated user to leave the team with the given id. This will not delete the team, and
all other members are still members of the team.
diff --git a/docs/api/users.md b/docs/api/users.md
index 3d5755b..2882cc4 100644
--- a/docs/api/users.md
+++ b/docs/api/users.md
@@ -88,7 +88,7 @@ interface Body {
task: string;
user: string;
started: number;
- finished: number;
+ finished?: number;
}[];
}
```
--
GitLab