From 4489ce4482b70c07d1f0cb9abb9384eb2d9acd28 Mon Sep 17 00:00:00 2001 From: Jacob O'Mara Date: Tue, 29 Oct 2024 10:56:03 +0000 Subject: [PATCH] Bug 38050: create admin CRUD endpoint definitions This patch creates the yaml definitions for the CRUD enpoints for virtualshelves/lists --- api/v1/swagger/definitions/list.yaml | 17 ++- api/v1/swagger/paths/lists.yaml | 209 ++++++++++++++++++++++++--- api/v1/swagger/swagger.yaml | 10 ++ 3 files changed, 218 insertions(+), 18 deletions(-) diff --git a/api/v1/swagger/definitions/list.yaml b/api/v1/swagger/definitions/list.yaml index 215a8af5dc..34d495eed0 100644 --- a/api/v1/swagger/definitions/list.yaml +++ b/api/v1/swagger/definitions/list.yaml @@ -2,8 +2,9 @@ type: object properties: list_id: - description: Interal identifier for the list + description: Internal identifier for the list type: integer + readOnly: true name: description: List name type: string @@ -11,25 +12,39 @@ properties: description: Date the list was created type: string format: date-time + readOnly: true updated_on_date: description: Date the list was last updated type: string format: date-time + readOnly: true owner_id: description: Internal identifier for the owning patron type: integer allow_change_from_owner: description: If the owner can change the contents type: boolean + default: true allow_change_from_others: description: If others can change the contents type: boolean + default: false public: description: If the list is public type: boolean + default: true default_sort_field: description: The field this list is sorted on by default type: string + default: 'title' + allow_change_from_permitted_staff: + description: If only permitted staff can change the contents + type: boolean + default: false + allow_change_from_staff: + description: If staff can change the contents + type: boolean + default: false additionalProperties: false required: - list_id diff --git a/api/v1/swagger/paths/lists.yaml b/api/v1/swagger/paths/lists.yaml index 596c1ef314..01e90cda70 100644 --- a/api/v1/swagger/paths/lists.yaml +++ b/api/v1/swagger/paths/lists.yaml @@ -1,23 +1,18 @@ --- -"/public/lists": +/lists: get: - x-mojo-to: Lists#list_public - operationId: listListsPublic + x-mojo-to: Lists#list description: "This resource returns a list of existing bibliographic lists." - summary: List bibliographic lists + x-koha-authorization: + permissions: + tools: manage_patron_lists + operationId: listLists tags: - lists + summary: List bibliographic lists + produces: + - application/json parameters: - - name: only_mine - in: query - description: Only return the users' lists - required: false - type: string - - name: only_public - in: query - description: Only return public lists - required: false - type: string - $ref: "../swagger.yaml#/parameters/match" - $ref: "../swagger.yaml#/parameters/order_by" - $ref: "../swagger.yaml#/parameters/page" @@ -25,8 +20,6 @@ - $ref: "../swagger.yaml#/parameters/q_param" - $ref: "../swagger.yaml#/parameters/q_body" - $ref: "../swagger.yaml#/parameters/request_id_header" - produces: - - application/json responses: "200": description: A list of lists @@ -40,7 +33,6 @@ * `bad_request` * `invalid_query` - * `only_mine_forbidden` schema: $ref: "../swagger.yaml#/definitions/error" "403": @@ -58,3 +50,186 @@ description: Under maintenance schema: $ref: "../swagger.yaml#/definitions/error" + + + post: + x-mojo-to: Lists#create + x-koha-authorization: + permissions: + tools: manage_patron_lists + operationId: createList + tags: + - lists + description: "This resource creates a bibliographic list owned by a specified user." + summary: Create a new list + produces: + - application/json + parameters: + - name: body + in: body + description: A JSON object containing information about the new list + required: true + schema: + $ref: "../swagger.yaml#/definitions/list" + responses: + "201": + description: List added + schema: + $ref: "../swagger.yaml#/definitions/list" + "400": + description: Bad request + schema: + $ref: "../swagger.yaml#/definitions/error" + "401": + description: Authentication required + schema: + $ref: "../swagger.yaml#/definitions/error" + "403": + description: Access forbidden + schema: + $ref: "../swagger.yaml#/definitions/error" + "500": + description: | + Internal server error. Possible `error_code` attribute values: + + * `internal_server_error` + schema: + $ref: "../swagger.yaml#/definitions/error" + "503": + description: Under maintenance + schema: + $ref: "../swagger.yaml#/definitions/error" + +/lists/{list_id}: + get: + x-mojo-to: Lists#read + x-koha-authorization: + permissions: + tools: manage_patron_lists + description: "This resource returns information on a specific existing bibliographic list." + operationId: readList + tags: + - lists + summary: Retrieve a specific list + produces: + - application/json + parameters: + - $ref: "../swagger.yaml#/parameters/list_id_pp" + responses: + "200": + description: OK + schema: + $ref: "../swagger.yaml#/definitions/list" + "400": + description: Bad request + schema: + $ref: "../swagger.yaml#/definitions/error" + "403": + description: Access forbidden + schema: + $ref: "../swagger.yaml#/definitions/error" + "404": + description: Not found + schema: + $ref: "../swagger.yaml#/definitions/error" + "500": + description: | + Internal server error. Possible `error_code` attribute values: + + * `internal_server_error` + schema: + $ref: "../swagger.yaml#/definitions/error" + "503": + description: Under maintenance + schema: + $ref: "../swagger.yaml#/definitions/error" + + put: + x-mojo-to: Lists#update + x-koha-authorization: + permissions: + tools: manage_patron_lists + operationId: updateList + description: 'Update a specific list' + tags: + - lists + summary: Update a specific list + produces: + - application/json + parameters: + - $ref: "../swagger.yaml#/parameters/list_id_pp" + - name: body + in: body + description: A list object + required: true + schema: + $ref: "../swagger.yaml#/definitions/list" + responses: + "200": + description: A city + schema: + $ref: "../swagger.yaml#/definitions/list" + "400": + description: Bad request + schema: + $ref: "../swagger.yaml#/definitions/error" + "401": + description: Authentication required + schema: + $ref: "../swagger.yaml#/definitions/error" + "403": + description: Access forbidden + schema: + $ref: "../swagger.yaml#/definitions/error" + "404": + description: Not found + schema: + $ref: "../swagger.yaml#/definitions/error" + "500": + description: | + Internal server error. Possible `error_code` attribute values: + + * `internal_server_error` + schema: + $ref: "../swagger.yaml#/definitions/error" + "503": + description: Under maintenance + schema: + $ref: "../swagger.yaml#/definitions/error" + + delete: + x-mojo-to: Lists#delete + x-koha-authorization: + permissions: + tools: manage_patron_lists + operationId: deleteList + tags: + - lists + summary: Delete a specific list + produces: + - application/json + parameters: + - $ref: "../swagger.yaml#/parameters/list_id_pp" + responses: + "204": + description: List deleted + "401": + description: Authentication required + schema: + $ref: "../swagger.yaml#/definitions/error" + "403": + description: Access forbidden + schema: + $ref: "../swagger.yaml#/definitions/error" + "404": + description: List not found + schema: + $ref: "../swagger.yaml#/definitions/error" + "500": + description: Internal error + schema: + $ref: "../swagger.yaml#/definitions/error" + "503": + description: Under maintenance + schema: + $ref: "../swagger.yaml#/definitions/error" diff --git a/api/v1/swagger/swagger.yaml b/api/v1/swagger/swagger.yaml index ff7b94a174..51ed2bb3e9 100644 --- a/api/v1/swagger/swagger.yaml +++ b/api/v1/swagger/swagger.yaml @@ -445,6 +445,10 @@ paths: $ref: "./paths/libraries.yaml#/~1libraries~1{library_id}~1cash_registers" "/libraries/{library_id}/desks": $ref: "./paths/libraries.yaml#/~1libraries~1{library_id}~1desks" + /lists: + $ref: ./paths/lists.yaml#/~1lists + "/lists/{id}": + $ref: "./paths/lists.yaml#/~1lists~1{id}" "/oauth/login/{provider_code}/{interface}": $ref: ./paths/oauth.yaml#/~1oauth~1login~1{provider_code}~1{interface} /oauth/token: @@ -806,6 +810,12 @@ parameters: name: license_id required: true type: integer + list_id_pp: + description: list internal identifier + in: path + name: list_id + required: true + type: integer match: description: Matching criteria enum: -- 2.39.2