From 95d711ee2e06102274825e8a804fcded22ae95c4 Mon Sep 17 00:00:00 2001 From: Amri Sannang Date: Mon, 18 Mar 2024 15:22:15 +1100 Subject: [PATCH 1/8] Add curriculum node add/remove to/from folder endpoints [SA-17416] --- openapi/openapi.yaml | 3 ++ ...rriculum@usage@{id}@folder@{folderId}.yaml | 48 +++++++++++++++++++ 2 files changed, 51 insertions(+) create mode 100644 openapi/paths/api@curriculum@usage@{id}@folder@{folderId}.yaml diff --git a/openapi/openapi.yaml b/openapi/openapi.yaml index b93167dc..469d2a39 100644 --- a/openapi/openapi.yaml +++ b/openapi/openapi.yaml @@ -241,6 +241,9 @@ paths: /api/curriculum/usage/{id}: $ref: 'paths/api@curriculum@usage@{id}.yaml' + /api/curriculum/usage/{id}/folder/{folderId}: + $ref: 'paths/api@curriculum@usage@{id}@folder@{folderId}.yaml' + /api/search: $ref: 'paths/api@search.yaml' diff --git a/openapi/paths/api@curriculum@usage@{id}@folder@{folderId}.yaml b/openapi/paths/api@curriculum@usage@{id}@folder@{folderId}.yaml new file mode 100644 index 00000000..37a43af3 --- /dev/null +++ b/openapi/paths/api@curriculum@usage@{id}@folder@{folderId}.yaml @@ -0,0 +1,48 @@ +post: + operationId: curriculumApiUsageFolder.postSingleFolderUsage + tags: [curriculum] + summary: Add curriculum node to a folder + description: | + Add a single curriculum node to a folder. + + Returns a 204 response if the node was added, or a 409 if it was already on + the folder. + responses: + '204': + description: The curriculum node was added successfully. + '409': + description: The curriculum node already exists on the folder. + default: + $ref: ../components/responses/problem.yaml + +delete: + operationId: curriculumApiUsageFolder.deleteSingleFolderUsage + tags: [curriculum] + summary: Remove curriculum node to a folder + description: | + Remove a single curriculum node from a folder. + + Returns a 204 response if the node was removed, or a 404 if it did not + already exist on the folder. + responses: + '204': + description: The curriculum node was removed successfully. + '404': + description: The curriculum node does not exist on the folder. + default: + $ref: ../components/responses/problem.yaml + +parameters: + - $ref: ../components/parameters/id.yaml + - name: folderId + in: path + description: | + The ID of the folder to modify curriculum nodes for. + required: true + schema: + type: integer + format: int32 + minimum: 1 + + - $ref: ../components/parameters/cursor.yaml + - $ref: ../components/parameters/limit.yaml From 5caf33fb356787d46fa556b91593f34aa3b382e9 Mon Sep 17 00:00:00 2001 From: Amri Sannang Date: Mon, 18 Mar 2024 15:26:44 +1100 Subject: [PATCH 2/8] Start adding docs for set nodes endpoint [SA-17416] --- openapi/openapi.yaml | 3 +++ ...pi@curriculum@usage@folder@{folderId}.yaml | 27 +++++++++++++++++++ ...rriculum@usage@{id}@folder@{folderId}.yaml | 3 --- 3 files changed, 30 insertions(+), 3 deletions(-) create mode 100644 openapi/paths/api@curriculum@usage@folder@{folderId}.yaml diff --git a/openapi/openapi.yaml b/openapi/openapi.yaml index 469d2a39..4a4e3e68 100644 --- a/openapi/openapi.yaml +++ b/openapi/openapi.yaml @@ -244,6 +244,9 @@ paths: /api/curriculum/usage/{id}/folder/{folderId}: $ref: 'paths/api@curriculum@usage@{id}@folder@{folderId}.yaml' + /api/curriculum/usage/folder/{folderId}: + $ref: 'paths/api@curriculum@usage@folder@{folderId}.yaml' + /api/search: $ref: 'paths/api@search.yaml' diff --git a/openapi/paths/api@curriculum@usage@folder@{folderId}.yaml b/openapi/paths/api@curriculum@usage@folder@{folderId}.yaml new file mode 100644 index 00000000..b0ef89d6 --- /dev/null +++ b/openapi/paths/api@curriculum@usage@folder@{folderId}.yaml @@ -0,0 +1,27 @@ +post: + operationId: curriculumApiUsageFolder.postFolderUsage + tags: [curriculum] + summary: Set curriculum nodes associated with a folder + description: | + Set the curriculum nodes associated with a folder. + + Returns a 204 response if the node were set, or a 404 if any node to be + added was not found. + responses: + '204': + description: The curriculum node was added successfully. + '404': + description: One or more curriculum nodes to be added were not found. + default: + $ref: ../components/responses/problem.yaml + +parameters: + - name: folderId + in: path + description: | + The ID of the folder to modify curriculum nodes for. + required: true + schema: + type: integer + format: int32 + minimum: 1 diff --git a/openapi/paths/api@curriculum@usage@{id}@folder@{folderId}.yaml b/openapi/paths/api@curriculum@usage@{id}@folder@{folderId}.yaml index 37a43af3..d0bd3571 100644 --- a/openapi/paths/api@curriculum@usage@{id}@folder@{folderId}.yaml +++ b/openapi/paths/api@curriculum@usage@{id}@folder@{folderId}.yaml @@ -43,6 +43,3 @@ parameters: type: integer format: int32 minimum: 1 - - - $ref: ../components/parameters/cursor.yaml - - $ref: ../components/parameters/limit.yaml From 14e573b2b89c4a6694e6199aca9734b42dcd87eb Mon Sep 17 00:00:00 2001 From: Amri Sannang Date: Mon, 18 Mar 2024 15:39:09 +1100 Subject: [PATCH 3/8] Add request body [SA-17416] --- .../api@curriculum@usage@folder@{folderId}.yaml | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/openapi/paths/api@curriculum@usage@folder@{folderId}.yaml b/openapi/paths/api@curriculum@usage@folder@{folderId}.yaml index b0ef89d6..500bf760 100644 --- a/openapi/paths/api@curriculum@usage@folder@{folderId}.yaml +++ b/openapi/paths/api@curriculum@usage@folder@{folderId}.yaml @@ -7,6 +7,20 @@ post: Returns a 204 response if the node were set, or a 404 if any node to be added was not found. + requestBody: + description: | + An array of curriculum nodes to associate with the folder. + + This will override the folder's current association completely: any nodes + not in this list will be disassociated from the folder. + (If this is an empty list, the folder will have no nodes associated.) + content: + application/json: + schema: + type: array + items: + $ref: ../components/schemas/curriculumItem.yaml + responses: '204': description: The curriculum node was added successfully. From 8b3fea960937a628548b47171079eba9f0232fc5 Mon Sep 17 00:00:00 2001 From: Amri Sannang Date: Mon, 18 Mar 2024 15:42:14 +1100 Subject: [PATCH 4/8] From [SA-17416] --- openapi/paths/api@curriculum@usage@{id}@folder@{folderId}.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/openapi/paths/api@curriculum@usage@{id}@folder@{folderId}.yaml b/openapi/paths/api@curriculum@usage@{id}@folder@{folderId}.yaml index d0bd3571..6ebaf33c 100644 --- a/openapi/paths/api@curriculum@usage@{id}@folder@{folderId}.yaml +++ b/openapi/paths/api@curriculum@usage@{id}@folder@{folderId}.yaml @@ -18,7 +18,7 @@ post: delete: operationId: curriculumApiUsageFolder.deleteSingleFolderUsage tags: [curriculum] - summary: Remove curriculum node to a folder + summary: Remove curriculum node from a folder description: | Remove a single curriculum node from a folder. From a5569c1655ad456f9d66abe19b38c41c6b46a840 Mon Sep 17 00:00:00 2001 From: Amri Sannang Date: Mon, 18 Mar 2024 15:45:45 +1100 Subject: [PATCH 5/8] Move description [SA-17416] --- .../api@curriculum@usage@folder@{folderId}.yaml | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/openapi/paths/api@curriculum@usage@folder@{folderId}.yaml b/openapi/paths/api@curriculum@usage@folder@{folderId}.yaml index 500bf760..9f6ba069 100644 --- a/openapi/paths/api@curriculum@usage@folder@{folderId}.yaml +++ b/openapi/paths/api@curriculum@usage@folder@{folderId}.yaml @@ -8,15 +8,16 @@ post: Returns a 204 response if the node were set, or a 404 if any node to be added was not found. requestBody: - description: | - An array of curriculum nodes to associate with the folder. - - This will override the folder's current association completely: any nodes - not in this list will be disassociated from the folder. - (If this is an empty list, the folder will have no nodes associated.) content: application/json: schema: + description: | + An array of curriculum nodes to associate with the folder. + + This will override the folder's current association completely: any + nodes not in this list will be disassociated from the folder. + (If this is empty, the folder will have no nodes associated.) + type: array items: $ref: ../components/schemas/curriculumItem.yaml From a70b1ecb8033a31c1468d3e2822514afeeea19e9 Mon Sep 17 00:00:00 2001 From: Amri Sannang Date: Wed, 20 Mar 2024 14:53:26 +1100 Subject: [PATCH 6/8] Add new params for ancestors/descendants/returnFormat [SA-17416] --- .../components/parameters/curriculum-ancestors.yaml | 11 +++++++++++ .../parameters/curriculum-descendants.yaml | 11 +++++++++++ .../components/parameters/curriculum-folderId.yaml | 9 +++++++++ .../parameters/curriculum-returnFormat.yaml | 10 ++++++++++ .../api@curriculum@usage@folder@{folderId}.yaml | 13 ++++--------- ...api@curriculum@usage@{id}@folder@{folderId}.yaml | 13 ++++--------- 6 files changed, 49 insertions(+), 18 deletions(-) create mode 100644 openapi/components/parameters/curriculum-ancestors.yaml create mode 100644 openapi/components/parameters/curriculum-descendants.yaml create mode 100644 openapi/components/parameters/curriculum-folderId.yaml create mode 100644 openapi/components/parameters/curriculum-returnFormat.yaml diff --git a/openapi/components/parameters/curriculum-ancestors.yaml b/openapi/components/parameters/curriculum-ancestors.yaml new file mode 100644 index 00000000..6f1e188f --- /dev/null +++ b/openapi/components/parameters/curriculum-ancestors.yaml @@ -0,0 +1,11 @@ +name: ancestors +in: query +description: | + The number of levels of ancestry to retrieve, if this endpoint is + returning a tree. +schema: + type: integer + format: int32 + minimum: 0 + maximum: 50 + default: 50 diff --git a/openapi/components/parameters/curriculum-descendants.yaml b/openapi/components/parameters/curriculum-descendants.yaml new file mode 100644 index 00000000..ed0d5709 --- /dev/null +++ b/openapi/components/parameters/curriculum-descendants.yaml @@ -0,0 +1,11 @@ +name: descendants +in: query +description: | + The number of levels of descendants to retrieve, if this endpoint is + returning a tree. +schema: + type: integer + format: int32 + minimum: 0 + maximum: 50 + default: 50 diff --git a/openapi/components/parameters/curriculum-folderId.yaml b/openapi/components/parameters/curriculum-folderId.yaml new file mode 100644 index 00000000..53960b45 --- /dev/null +++ b/openapi/components/parameters/curriculum-folderId.yaml @@ -0,0 +1,9 @@ +name: folderId +in: path +description: | + The ID of the folder to modify curriculum nodes for. +required: true +schema: + type: integer + format: int32 + minimum: 1 diff --git a/openapi/components/parameters/curriculum-returnFormat.yaml b/openapi/components/parameters/curriculum-returnFormat.yaml new file mode 100644 index 00000000..9d101101 --- /dev/null +++ b/openapi/components/parameters/curriculum-returnFormat.yaml @@ -0,0 +1,10 @@ +name: returnFormat +in: query +description: | + The format to return the folder's ancestry in. +schema: + type: string + enum: + - tree + - list + default: list diff --git a/openapi/paths/api@curriculum@usage@folder@{folderId}.yaml b/openapi/paths/api@curriculum@usage@folder@{folderId}.yaml index 9f6ba069..44ee5d7b 100644 --- a/openapi/paths/api@curriculum@usage@folder@{folderId}.yaml +++ b/openapi/paths/api@curriculum@usage@folder@{folderId}.yaml @@ -31,12 +31,7 @@ post: $ref: ../components/responses/problem.yaml parameters: - - name: folderId - in: path - description: | - The ID of the folder to modify curriculum nodes for. - required: true - schema: - type: integer - format: int32 - minimum: 1 + - $ref: ../components/parameters/curriculum-folderId.yaml + - $ref: ../components/parameters/curriculum-ancestors.yaml + - $ref: ../components/parameters/curriculum-descendants.yaml + - $ref: ../components/parameters/curriculum-returnFormat.yaml diff --git a/openapi/paths/api@curriculum@usage@{id}@folder@{folderId}.yaml b/openapi/paths/api@curriculum@usage@{id}@folder@{folderId}.yaml index 6ebaf33c..e864471e 100644 --- a/openapi/paths/api@curriculum@usage@{id}@folder@{folderId}.yaml +++ b/openapi/paths/api@curriculum@usage@{id}@folder@{folderId}.yaml @@ -34,12 +34,7 @@ delete: parameters: - $ref: ../components/parameters/id.yaml - - name: folderId - in: path - description: | - The ID of the folder to modify curriculum nodes for. - required: true - schema: - type: integer - format: int32 - minimum: 1 + - $ref: ../components/parameters/curriculum-folderId.yaml + - $ref: ../components/parameters/curriculum-ancestors.yaml + - $ref: ../components/parameters/curriculum-descendants.yaml + - $ref: ../components/parameters/curriculum-returnFormat.yaml From d4ee60d689aa5d45f4bb9103882de87fba5f6bff Mon Sep 17 00:00:00 2001 From: Amri Sannang Date: Wed, 20 Mar 2024 15:08:44 +1100 Subject: [PATCH 7/8] Update return format and responses [SA-17416] --- .../parameters/curriculum-returnFormat.yaml | 11 ++++++++++- ...api@curriculum@usage@folder@{folderId}.yaml | 18 ++++++++++++++---- ...urriculum@usage@{id}@folder@{folderId}.yaml | 8 ++++---- 3 files changed, 28 insertions(+), 9 deletions(-) diff --git a/openapi/components/parameters/curriculum-returnFormat.yaml b/openapi/components/parameters/curriculum-returnFormat.yaml index 9d101101..374cb059 100644 --- a/openapi/components/parameters/curriculum-returnFormat.yaml +++ b/openapi/components/parameters/curriculum-returnFormat.yaml @@ -1,7 +1,16 @@ name: returnFormat in: query description: | - The format to return the folder's ancestry in. + The format to return the folder's curriculum nodes in. + * tree: return a response containing the below relations, reduced to a single + tree structure: + * all top-level curriculum nodes which are ancestors of the folder's nodes + (up to `ancestors` levels up) + * the folder's actual curriculum nodes + * all descendants of the folder's curriculum nodes + (up to `descendants` levels down) + * list: return a response containing only the folder's curriculum nodes, in a + flat structure schema: type: string enum: diff --git a/openapi/paths/api@curriculum@usage@folder@{folderId}.yaml b/openapi/paths/api@curriculum@usage@folder@{folderId}.yaml index 44ee5d7b..cf767ea9 100644 --- a/openapi/paths/api@curriculum@usage@folder@{folderId}.yaml +++ b/openapi/paths/api@curriculum@usage@folder@{folderId}.yaml @@ -5,8 +5,8 @@ post: description: | Set the curriculum nodes associated with a folder. - Returns a 204 response if the node were set, or a 404 if any node to be - added was not found. + Returns a 200 response with the new structure the nodes were set, + or a 404 if any node to be added was not found. requestBody: content: application/json: @@ -23,8 +23,18 @@ post: $ref: ../components/schemas/curriculumItem.yaml responses: - '204': - description: The curriculum node was added successfully. + '200': + description: | + The new list of curriculum nodes for this folder. + + If parameter `returnFormat` is `tree`, then this will return a tree + beginning from the topmost node, + content: + application/json: + schema: + type: array + items: + $ref: ../components/schemas/curriculumItem.yaml '404': description: One or more curriculum nodes to be added were not found. default: diff --git a/openapi/paths/api@curriculum@usage@{id}@folder@{folderId}.yaml b/openapi/paths/api@curriculum@usage@{id}@folder@{folderId}.yaml index e864471e..9d15c8bc 100644 --- a/openapi/paths/api@curriculum@usage@{id}@folder@{folderId}.yaml +++ b/openapi/paths/api@curriculum@usage@{id}@folder@{folderId}.yaml @@ -5,8 +5,8 @@ post: description: | Add a single curriculum node to a folder. - Returns a 204 response if the node was added, or a 409 if it was already on - the folder. + Returns a 200 response with the new structure if the node was added, + or a 409 if it was already on the folder. responses: '204': description: The curriculum node was added successfully. @@ -22,8 +22,8 @@ delete: description: | Remove a single curriculum node from a folder. - Returns a 204 response if the node was removed, or a 404 if it did not - already exist on the folder. + Returns a 200 response with the new structure if the node was removed, + or a 404 if it did not already exist on the folder. responses: '204': description: The curriculum node was removed successfully. From 1b2203ba7e18567bfaf5f667350a5f5e41572ba5 Mon Sep 17 00:00:00 2001 From: Amri Sannang Date: Wed, 20 Mar 2024 15:22:59 +1100 Subject: [PATCH 8/8] Add new response types and their examples [SA-17416] --- .../examples/curriculumFolderUsage-list.yaml | 7 +++++++ .../examples/curriculumFolderUsage-tree.yaml | 20 +++++++++++++++++++ .../responses/curriculumFolderUsage-list.yaml | 16 +++++++++++++++ .../components/schemas/curriculumItem.yaml | 10 ++++++++-- ...pi@curriculum@usage@folder@{folderId}.yaml | 12 +---------- ...rriculum@usage@{id}@folder@{folderId}.yaml | 8 ++++---- 6 files changed, 56 insertions(+), 17 deletions(-) create mode 100644 openapi/components/examples/curriculumFolderUsage-list.yaml create mode 100644 openapi/components/examples/curriculumFolderUsage-tree.yaml create mode 100644 openapi/components/responses/curriculumFolderUsage-list.yaml diff --git a/openapi/components/examples/curriculumFolderUsage-list.yaml b/openapi/components/examples/curriculumFolderUsage-list.yaml new file mode 100644 index 00000000..2fb90aa1 --- /dev/null +++ b/openapi/components/examples/curriculumFolderUsage-list.yaml @@ -0,0 +1,7 @@ +value: + - id: 100 + name: Self-awareness + code: GCPSC-SEA + - id: 200 + name: Self-discipline + code: GCPSC-SED diff --git a/openapi/components/examples/curriculumFolderUsage-tree.yaml b/openapi/components/examples/curriculumFolderUsage-tree.yaml new file mode 100644 index 00000000..610d087d --- /dev/null +++ b/openapi/components/examples/curriculumFolderUsage-tree.yaml @@ -0,0 +1,20 @@ +value: + - id: 1 + name: Traits + children: + - id: 100 + name: Self-awareness + code: GCPSC-SEA + children: + - id: 101 + name: Test 1 + - id: 102 + name: Test 2 + - id: 200 + name: Self-discipline + code: GCPSC-SED + children: + - id: 201 + name: Test 1 + - id: 202 + name: Test 2 diff --git a/openapi/components/responses/curriculumFolderUsage-list.yaml b/openapi/components/responses/curriculumFolderUsage-list.yaml new file mode 100644 index 00000000..7469d163 --- /dev/null +++ b/openapi/components/responses/curriculumFolderUsage-list.yaml @@ -0,0 +1,16 @@ +description: | + The new list of curriculum nodes for this folder. + + If parameter `returnFormat` is `tree`, then this will return a tree + beginning from the topmost node; otherwise it will return an empty list. +content: + application/json: + schema: + type: array + items: + $ref: ../schemas/curriculumItem.yaml + examples: + list: + $ref: ../examples/curriculumFolderUsage-list.yaml + tree: + $ref: ../examples/curriculumFolderUsage-tree.yaml diff --git a/openapi/components/schemas/curriculumItem.yaml b/openapi/components/schemas/curriculumItem.yaml index 8ecb92da..b55c4d17 100644 --- a/openapi/components/schemas/curriculumItem.yaml +++ b/openapi/components/schemas/curriculumItem.yaml @@ -1,5 +1,5 @@ title: a Curriculum Code -description: A Curriculm Code +description: A Curriculum Code readOnly: true type: object properties: @@ -10,4 +10,10 @@ properties: example: Self-awareness code: type: string - example: GCPSC-SEA \ No newline at end of file + example: GCPSC-SEA + children: + description: | + Optional list of child nodes of this curriculum node. + type: array + items: + $ref: ./curriculumItem.yaml diff --git a/openapi/paths/api@curriculum@usage@folder@{folderId}.yaml b/openapi/paths/api@curriculum@usage@folder@{folderId}.yaml index cf767ea9..10ae68fc 100644 --- a/openapi/paths/api@curriculum@usage@folder@{folderId}.yaml +++ b/openapi/paths/api@curriculum@usage@folder@{folderId}.yaml @@ -24,17 +24,7 @@ post: responses: '200': - description: | - The new list of curriculum nodes for this folder. - - If parameter `returnFormat` is `tree`, then this will return a tree - beginning from the topmost node, - content: - application/json: - schema: - type: array - items: - $ref: ../components/schemas/curriculumItem.yaml + $ref: ../components/responses/curriculumFolderUsage-list.yaml '404': description: One or more curriculum nodes to be added were not found. default: diff --git a/openapi/paths/api@curriculum@usage@{id}@folder@{folderId}.yaml b/openapi/paths/api@curriculum@usage@{id}@folder@{folderId}.yaml index 9d15c8bc..6cfb50ed 100644 --- a/openapi/paths/api@curriculum@usage@{id}@folder@{folderId}.yaml +++ b/openapi/paths/api@curriculum@usage@{id}@folder@{folderId}.yaml @@ -8,8 +8,8 @@ post: Returns a 200 response with the new structure if the node was added, or a 409 if it was already on the folder. responses: - '204': - description: The curriculum node was added successfully. + '200': + $ref: ../components/responses/curriculumFolderUsage-list.yaml '409': description: The curriculum node already exists on the folder. default: @@ -25,8 +25,8 @@ delete: Returns a 200 response with the new structure if the node was removed, or a 404 if it did not already exist on the folder. responses: - '204': - description: The curriculum node was removed successfully. + '200': + $ref: ../components/responses/curriculumFolderUsage-list.yaml '404': description: The curriculum node does not exist on the folder. default: