From bbb0e65c761af3c507e7fa3805b8e80df66f6fe0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Christian=20Kleinb=C3=B6lting?= Date: Mon, 11 Mar 2024 15:51:44 +0100 Subject: [PATCH] docs: Add Examples to /admin/groups endpoints (#3107) --- docs/03-endpoints/api-admin/index.md | 5 + .../generated-openapi/openapi-admin-api.yml | 344 ++++++++++++++++-- .../slice/admin/api/AdminPathVariables.scala | 2 +- .../webapi/slice/admin/api/Examples.scala | 130 +++++++ .../slice/admin/api/GroupsEndpoints.scala | 46 +-- .../slice/admin/domain/model/User.scala | 1 - 6 files changed, 475 insertions(+), 53 deletions(-) create mode 100644 webapi/src/main/scala/org/knora/webapi/slice/admin/api/Examples.scala diff --git a/docs/03-endpoints/api-admin/index.md b/docs/03-endpoints/api-admin/index.md index 2a16d7376f..f93493deff 100644 --- a/docs/03-endpoints/api-admin/index.md +++ b/docs/03-endpoints/api-admin/index.md @@ -1 +1,6 @@ + +We provide an [OpenAPI](https://spec.openapis.org/oas/latest.html) specification. The latest version is located at [api.dasch.swiss/api/docs/docs.yaml](https://api.dasch.swiss/api/docs/docs.yaml). +For an interactive documentation of all API endpoints, please visit [api.dasch.swiss/api/docs/](https://api.dasch.swiss/api/docs/). + + [OAD(./docs/03-endpoints/generated-openapi/openapi-admin-api.yml)] diff --git a/docs/03-endpoints/generated-openapi/openapi-admin-api.yml b/docs/03-endpoints/generated-openapi/openapi-admin-api.yml index fdb88fd5cd..399ec8ec70 100644 --- a/docs/03-endpoints/generated-openapi/openapi-admin-api.yml +++ b/docs/03-endpoints/generated-openapi/openapi-admin-api.yml @@ -1,7 +1,7 @@ openapi: 3.1.0 info: title: webapi-admin-api - version: v30.8.2-37-g3decf23-dirty-doc-integrate-admin-openapi-in-docs-DEV-3381 + version: v30.8.2-40-g7f95a2e-dirty-doc-polish-openapi-documentation servers: - url: http://localhost:3333 description: Local development server @@ -12,7 +12,7 @@ paths: get: tags: - Admin Groups - description: Returns all groups. + description: Return all groups. operationId: getAdminGroups responses: '200': @@ -21,6 +21,31 @@ paths: application/json: schema: $ref: '#/components/schemas/GroupsGetResponseADM' + example: + groups: + - descriptions: + - value: NewGroup description in English + language: en + - value: NewGroup Beschreibung auf Deutsch + language: de + id: http://rdfh.ch/groups/0042/a95UWs71KUklnFOe1rcw1w + name: NewGroup + project: + description: + - value: An example project + language: en + id: http://rdfh.ch/projects/0042 + keywords: + - example + - project + longname: Example Project + ontologies: [] + selfjoin: false + shortcode: '0001' + shortname: example + status: true + selfjoin: false + status: true '400': description: '' content: @@ -36,8 +61,9 @@ paths: post: tags: - Admin Groups - description: Creates a new group. - operationId: postAdminGroups + description: '**Required permissions**: User must SystemAdmin or ProjectAdmin + of the project the group is created in.' + operationId: Create new group parameters: - name: KnoraAuthenticationMFYGSLTEMFZWG2BOON3WS43THI2DIMY9 in: cookie @@ -49,6 +75,16 @@ paths: application/json: schema: $ref: '#/components/schemas/GroupCreateRequest' + example: + name: NewGroup + descriptions: + - value: NewGroup description in English + language: en + - value: NewGroup Beschreibung auf Deutsch + language: de + project: http://rdfh.ch/projects/0042 + status: true + selfjoin: false required: true responses: '200': @@ -57,6 +93,31 @@ paths: application/json: schema: $ref: '#/components/schemas/GroupGetResponseADM' + example: + group: + descriptions: + - value: NewGroup description in English + language: en + - value: NewGroup Beschreibung auf Deutsch + language: de + id: http://rdfh.ch/groups/0042/a95UWs71KUklnFOe1rcw1w + name: NewGroup + project: + description: + - value: An example project + language: en + id: http://rdfh.ch/projects/0042 + keywords: + - example + - project + longname: Example Project + ontologies: [] + selfjoin: false + shortcode: '0001' + shortname: example + status: true + selfjoin: false + status: true '400': description: '' content: @@ -88,7 +149,7 @@ paths: get: tags: - Admin Groups - description: Returns a single group identified by IRI. + description: Return a single group identified by its IRI. operationId: getAdminGroupsGroupiri parameters: - name: groupIri @@ -97,7 +158,7 @@ paths: required: true schema: type: string - example: http://rdfh.ch/groups/00FF/gNdJSNYrTDu2lGpPUs94nQ + example: http://rdfh.ch/groups/0042/a95UWs71KUklnFOe1rcw1w responses: '200': description: '' @@ -105,6 +166,31 @@ paths: application/json: schema: $ref: '#/components/schemas/GroupGetResponseADM' + example: + group: + descriptions: + - value: NewGroup description in English + language: en + - value: NewGroup Beschreibung auf Deutsch + language: de + id: http://rdfh.ch/groups/0042/a95UWs71KUklnFOe1rcw1w + name: NewGroup + project: + description: + - value: An example project + language: en + id: http://rdfh.ch/projects/0042 + keywords: + - example + - project + longname: Example Project + ontologies: [] + selfjoin: false + shortcode: '0001' + shortname: example + status: true + selfjoin: false + status: true '400': description: '' content: @@ -120,7 +206,7 @@ paths: put: tags: - Admin Groups - description: Updates a group. + description: Update a group's basic information. operationId: putAdminGroupsGroupiri parameters: - name: KnoraAuthenticationMFYGSLTEMFZWG2BOON3WS43THI2DIMY9 @@ -134,12 +220,21 @@ paths: required: true schema: type: string - example: http://rdfh.ch/groups/00FF/gNdJSNYrTDu2lGpPUs94nQ + example: http://rdfh.ch/groups/0042/a95UWs71KUklnFOe1rcw1w requestBody: content: application/json: schema: $ref: '#/components/schemas/GroupUpdateRequest' + example: + name: NewGroupNewName + descriptions: + - value: NewGroupNewName description in English + language: en + - value: NewGroupNewName Beschreibung auf Deutsch + language: de + status: false + selfjoin: true required: true responses: '200': @@ -148,6 +243,31 @@ paths: application/json: schema: $ref: '#/components/schemas/GroupGetResponseADM' + example: + group: + descriptions: + - value: NewGroup description in English + language: en + - value: NewGroup Beschreibung auf Deutsch + language: de + id: http://rdfh.ch/groups/0042/a95UWs71KUklnFOe1rcw1w + name: NewGroup + project: + description: + - value: An example project + language: en + id: http://rdfh.ch/projects/0042 + keywords: + - example + - project + longname: Example Project + ontologies: [] + selfjoin: false + shortcode: '0001' + shortname: example + status: true + selfjoin: false + status: true '400': description: '' content: @@ -192,7 +312,7 @@ paths: required: true schema: type: string - example: http://rdfh.ch/groups/00FF/gNdJSNYrTDu2lGpPUs94nQ + example: http://rdfh.ch/groups/0042/a95UWs71KUklnFOe1rcw1w responses: '200': description: '' @@ -200,6 +320,31 @@ paths: application/json: schema: $ref: '#/components/schemas/GroupGetResponseADM' + example: + group: + descriptions: + - value: NewGroup description in English + language: en + - value: NewGroup Beschreibung auf Deutsch + language: de + id: http://rdfh.ch/groups/0042/a95UWs71KUklnFOe1rcw1w + name: NewGroup + project: + description: + - value: An example project + language: en + id: http://rdfh.ch/projects/0042 + keywords: + - example + - project + longname: Example Project + ontologies: [] + selfjoin: false + shortcode: '0001' + shortname: example + status: true + selfjoin: false + status: true '400': description: '' content: @@ -231,7 +376,7 @@ paths: get: tags: - Admin Groups - description: Returns all members of a single group. + description: Return all members of a single group. operationId: getAdminGroupsGroupiriMembers parameters: - name: KnoraAuthenticationMFYGSLTEMFZWG2BOON3WS43THI2DIMY9 @@ -245,7 +390,7 @@ paths: required: true schema: type: string - example: http://rdfh.ch/groups/00FF/gNdJSNYrTDu2lGpPUs94nQ + example: http://rdfh.ch/groups/0042/a95UWs71KUklnFOe1rcw1w responses: '200': description: '' @@ -253,6 +398,140 @@ paths: application/json: schema: $ref: '#/components/schemas/GroupMembersGetResponseADM' + example: + members: + - email: user@exampl.com + familyName: Doe + givenName: Jane + groups: + - descriptions: + - value: NewGroup description in English + language: en + - value: NewGroup Beschreibung auf Deutsch + language: de + id: http://rdfh.ch/groups/0042/a95UWs71KUklnFOe1rcw1w + name: NewGroup + project: + description: + - value: An example project + language: en + id: http://rdfh.ch/projects/0042 + keywords: + - example + - project + longname: Example Project + ontologies: [] + selfjoin: false + shortcode: '0001' + shortname: example + status: true + selfjoin: false + status: true + id: http://rdfh.ch/users/0001 + lang: rm + permissions: + administrativePermissionsPerProject: {} + groupsPerProject: {} + projects: + - description: + - value: An example project + language: en + id: http://rdfh.ch/projects/0042 + keywords: + - example + - project + longname: Example Project + ontologies: [] + selfjoin: false + shortcode: '0001' + shortname: example + status: true + status: true + username: username + '400': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/GravsearchException' + '401': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/BadCredentialsException' + '403': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/ForbiddenException' + '404': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/NotFoundException' + security: + - httpAuth: [] + - httpAuth1: [] + /admin/groups/{groupIri}/status: + put: + tags: + - Admin Groups + description: Updates a group's status. + operationId: putAdminGroupsGroupiriStatus + parameters: + - name: KnoraAuthenticationMFYGSLTEMFZWG2BOON3WS43THI2DIMY9 + in: cookie + required: false + schema: + type: string + - name: groupIri + in: path + description: The IRI of a group. Must be URL-encoded. + required: true + schema: + type: string + example: http://rdfh.ch/groups/0042/a95UWs71KUklnFOe1rcw1w + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/GroupStatusUpdateRequest' + required: true + responses: + '200': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/GroupGetResponseADM' + example: + group: + descriptions: + - value: NewGroup description in English + language: en + - value: NewGroup Beschreibung auf Deutsch + language: de + id: http://rdfh.ch/groups/0042/a95UWs71KUklnFOe1rcw1w + name: NewGroup + project: + description: + - value: An example project + language: en + id: http://rdfh.ch/projects/0042 + keywords: + - example + - project + longname: Example Project + ontologies: [] + selfjoin: false + shortcode: '0001' + shortname: example + status: true + selfjoin: false + status: true '400': description: '' content: @@ -1034,7 +1313,7 @@ paths: required: true schema: type: string - example: http://rdfh.ch/groups/00FF/gNdJSNYrTDu2lGpPUs94nQ + example: http://rdfh.ch/groups/0042/a95UWs71KUklnFOe1rcw1w responses: '200': description: '' @@ -2690,7 +2969,7 @@ paths: required: true schema: type: string - example: http://rdfh.ch/users/-oKc5S4xSQ2E_50W0o1sFw + example: http://rdfh.ch/users/pt3a1SRSTdSYX-wwiXl3Uw responses: '200': description: '' @@ -2724,7 +3003,7 @@ paths: required: true schema: type: string - example: http://rdfh.ch/users/-oKc5S4xSQ2E_50W0o1sFw + example: http://rdfh.ch/users/pt3a1SRSTdSYX-wwiXl3Uw responses: '200': description: '' @@ -2758,7 +3037,7 @@ paths: required: true schema: type: string - example: http://rdfh.ch/users/-oKc5S4xSQ2E_50W0o1sFw + example: http://rdfh.ch/users/pt3a1SRSTdSYX-wwiXl3Uw responses: '200': description: '' @@ -2893,7 +3172,7 @@ paths: required: true schema: type: string - example: http://rdfh.ch/users/-oKc5S4xSQ2E_50W0o1sFw + example: http://rdfh.ch/users/pt3a1SRSTdSYX-wwiXl3Uw responses: '200': description: '' @@ -2945,7 +3224,7 @@ paths: required: true schema: type: string - example: http://rdfh.ch/users/-oKc5S4xSQ2E_50W0o1sFw + example: http://rdfh.ch/users/pt3a1SRSTdSYX-wwiXl3Uw responses: '200': description: '' @@ -3104,7 +3383,7 @@ paths: required: true schema: type: string - example: http://rdfh.ch/users/-oKc5S4xSQ2E_50W0o1sFw + example: http://rdfh.ch/users/pt3a1SRSTdSYX-wwiXl3Uw - name: projectIri in: path description: The IRI of a project. Must be URL-encoded. @@ -3163,7 +3442,7 @@ paths: required: true schema: type: string - example: http://rdfh.ch/users/-oKc5S4xSQ2E_50W0o1sFw + example: http://rdfh.ch/users/pt3a1SRSTdSYX-wwiXl3Uw - name: projectIri in: path description: The IRI of a project. Must be URL-encoded. @@ -3223,7 +3502,7 @@ paths: required: true schema: type: string - example: http://rdfh.ch/users/-oKc5S4xSQ2E_50W0o1sFw + example: http://rdfh.ch/users/pt3a1SRSTdSYX-wwiXl3Uw - name: projectIri in: path description: The IRI of a project. Must be URL-encoded. @@ -3282,7 +3561,7 @@ paths: required: true schema: type: string - example: http://rdfh.ch/users/-oKc5S4xSQ2E_50W0o1sFw + example: http://rdfh.ch/users/pt3a1SRSTdSYX-wwiXl3Uw - name: projectIri in: path description: The IRI of a project. Must be URL-encoded. @@ -3342,14 +3621,14 @@ paths: required: true schema: type: string - example: http://rdfh.ch/users/-oKc5S4xSQ2E_50W0o1sFw + example: http://rdfh.ch/users/pt3a1SRSTdSYX-wwiXl3Uw - name: groupIri in: path description: The IRI of a group. Must be URL-encoded. required: true schema: type: string - example: http://rdfh.ch/groups/00FF/gNdJSNYrTDu2lGpPUs94nQ + example: http://rdfh.ch/groups/0042/a95UWs71KUklnFOe1rcw1w responses: '200': description: '' @@ -3401,14 +3680,14 @@ paths: required: true schema: type: string - example: http://rdfh.ch/users/-oKc5S4xSQ2E_50W0o1sFw + example: http://rdfh.ch/users/pt3a1SRSTdSYX-wwiXl3Uw - name: groupIri in: path description: The IRI of a group. Must be URL-encoded. required: true schema: type: string - example: http://rdfh.ch/groups/00FF/gNdJSNYrTDu2lGpPUs94nQ + example: http://rdfh.ch/groups/0042/a95UWs71KUklnFOe1rcw1w responses: '200': description: '' @@ -3461,7 +3740,7 @@ paths: required: true schema: type: string - example: http://rdfh.ch/users/-oKc5S4xSQ2E_50W0o1sFw + example: http://rdfh.ch/users/pt3a1SRSTdSYX-wwiXl3Uw requestBody: content: application/json: @@ -3520,7 +3799,7 @@ paths: required: true schema: type: string - example: http://rdfh.ch/users/-oKc5S4xSQ2E_50W0o1sFw + example: http://rdfh.ch/users/pt3a1SRSTdSYX-wwiXl3Uw requestBody: content: application/json: @@ -3579,7 +3858,7 @@ paths: required: true schema: type: string - example: http://rdfh.ch/users/-oKc5S4xSQ2E_50W0o1sFw + example: http://rdfh.ch/users/pt3a1SRSTdSYX-wwiXl3Uw requestBody: content: application/json: @@ -3638,7 +3917,7 @@ paths: required: true schema: type: string - example: http://rdfh.ch/users/-oKc5S4xSQ2E_50W0o1sFw + example: http://rdfh.ch/users/pt3a1SRSTdSYX-wwiXl3Uw requestBody: content: application/json: @@ -4041,6 +4320,13 @@ components: type: array items: $ref: '#/components/schemas/User' + GroupStatusUpdateRequest: + required: + - status + type: object + properties: + status: + type: boolean GroupUpdateRequest: type: object properties: diff --git a/webapi/src/main/scala/org/knora/webapi/slice/admin/api/AdminPathVariables.scala b/webapi/src/main/scala/org/knora/webapi/slice/admin/api/AdminPathVariables.scala index beb83bbad0..e485a53c97 100644 --- a/webapi/src/main/scala/org/knora/webapi/slice/admin/api/AdminPathVariables.scala +++ b/webapi/src/main/scala/org/knora/webapi/slice/admin/api/AdminPathVariables.scala @@ -21,7 +21,7 @@ object AdminPathVariables { path[GroupIri] .name("groupIri") .description("The IRI of a group. Must be URL-encoded.") - .example(GroupIri.unsafeFrom("http://rdfh.ch/groups/00FF/gNdJSNYrTDu2lGpPUs94nQ")) + .example(Examples.GroupExample.groupIri) val permissionIri: EndpointInput.PathCapture[PermissionIri] = path[PermissionIri]("permissionIri") diff --git a/webapi/src/main/scala/org/knora/webapi/slice/admin/api/Examples.scala b/webapi/src/main/scala/org/knora/webapi/slice/admin/api/Examples.scala new file mode 100644 index 0000000000..32451e326d --- /dev/null +++ b/webapi/src/main/scala/org/knora/webapi/slice/admin/api/Examples.scala @@ -0,0 +1,130 @@ +/* + * Copyright © 2021 - 2024 Swiss National Data and Service Center for the Humanities and/or DaSCH Service Platform contributors. + * SPDX-License-Identifier: Apache-2.0 + */ + +package org.knora.webapi.slice.admin.api + +import dsp.valueobjects.V2 +import org.knora.webapi.messages.admin.responder.groupsmessages.GroupGetResponseADM +import org.knora.webapi.messages.admin.responder.groupsmessages.GroupsGetResponseADM +import org.knora.webapi.messages.admin.responder.permissionsmessages.PermissionsDataADM +import org.knora.webapi.messages.admin.responder.projectsmessages.ProjectADM +import org.knora.webapi.messages.admin.responder.usersmessages.GroupMembersGetResponseADM +import org.knora.webapi.messages.store.triplestoremessages.StringLiteralV2 +import org.knora.webapi.slice.admin.api.Examples.GroupExample.groupName +import org.knora.webapi.slice.admin.api.GroupsRequests.GroupCreateRequest +import org.knora.webapi.slice.admin.api.GroupsRequests.GroupUpdateRequest +import org.knora.webapi.slice.admin.domain.model.Email +import org.knora.webapi.slice.admin.domain.model.FamilyName +import org.knora.webapi.slice.admin.domain.model.GivenName +import org.knora.webapi.slice.admin.domain.model.Group +import org.knora.webapi.slice.admin.domain.model.GroupDescriptions +import org.knora.webapi.slice.admin.domain.model.GroupIri +import org.knora.webapi.slice.admin.domain.model.GroupName +import org.knora.webapi.slice.admin.domain.model.GroupSelfJoin +import org.knora.webapi.slice.admin.domain.model.GroupStatus +import org.knora.webapi.slice.admin.domain.model.KnoraProject.ProjectIri +import org.knora.webapi.slice.admin.domain.model.User +import org.knora.webapi.slice.admin.domain.model.UserIri +import org.knora.webapi.slice.admin.domain.model.UserStatus +import org.knora.webapi.slice.admin.domain.model.Username + +object Examples { + + object ProjectExample { + val projectIri: ProjectIri = ProjectIri.unsafeFrom("http://rdfh.ch/projects/0042") + } + + object GroupExample { + val groupIri: GroupIri = GroupIri.unsafeFrom("http://rdfh.ch/groups/0042/a95UWs71KUklnFOe1rcw1w") + + val groupName: GroupName = GroupName.unsafeFrom("NewGroup") + + val groupDescriptions: GroupDescriptions = GroupDescriptions.unsafeFrom( + Seq( + V2.StringLiteralV2(s"${groupName.value} description in English", Some("en")), + V2.StringLiteralV2(s"${groupName.value} Beschreibung auf Deutsch", Some("de")), + ), + ) + } + + object UserExample { + val userIri: UserIri = UserIri.unsafeFrom("http://rdfh.ch/users/0001") + val username: Username = Username.unsafeFrom("username") + val email: Email = Email.unsafeFrom("user@exampl.com") + val familyName: FamilyName = FamilyName.unsafeFrom("Doe") + val givenName: GivenName = GivenName.unsafeFrom("Jane") + val userStatus: UserStatus = UserStatus.Active + } + + object GroupEndpointsExample { + val groupCreateRequest: GroupCreateRequest = GroupCreateRequest( + name = GroupExample.groupName, + descriptions = GroupExample.groupDescriptions, + project = ProjectExample.projectIri, + status = GroupStatus.active, + selfjoin = GroupSelfJoin.disabled, + ) + + private val newGroupName: GroupName = GroupName.unsafeFrom("NewGroupNewName") + + val groupUpdateRequest: GroupUpdateRequest = GroupUpdateRequest( + name = Option(newGroupName), + descriptions = Option( + GroupDescriptions.unsafeFrom( + Seq( + V2.StringLiteralV2(s"${newGroupName.value} description in English", Some("en")), + V2.StringLiteralV2(s"${newGroupName.value} Beschreibung auf Deutsch", Some("de")), + ), + ), + ), + status = Option(GroupStatus.inactive), + selfjoin = Option(GroupSelfJoin.enabled), + ) + + private val project: ProjectADM = ProjectADM( + id = ProjectExample.projectIri.value, + shortname = "example", + shortcode = "0001", + longname = Some("Example Project"), + description = Seq(V2.StringLiteralV2("An example project", Some("en"))), + keywords = Seq("example", "project"), + logo = None, + status = true, + ontologies = Seq.empty, + selfjoin = false, + ) + + private val group = Group( + id = GroupExample.groupIri.value, + name = groupName.value, + descriptions = Seq( + StringLiteralV2(s"${groupName.value} description in English", Some("en")), + StringLiteralV2(s"${groupName.value} Beschreibung auf Deutsch", Some("de")), + ), + project = project, + status = GroupStatus.active.value, + selfjoin = GroupSelfJoin.disabled.value, + ) + + val groupGetResponseADM: GroupGetResponseADM = GroupGetResponseADM(group) + + val groupsGetResponseADM: GroupsGetResponseADM = GroupsGetResponseADM(Seq(group)) + + private val user = User( + id = UserExample.userIri.value, + username = UserExample.username.value, + email = UserExample.email.value, + givenName = UserExample.givenName.value, + familyName = UserExample.familyName.value, + status = UserExample.userStatus.value, + lang = "rm", + password = None, + groups = Seq(group), + projects = Seq(project), + permissions = PermissionsDataADM.apply(Map.empty), + ) + val groupGetMembersResponse: GroupMembersGetResponseADM = GroupMembersGetResponseADM(Seq(user)) + } +} diff --git a/webapi/src/main/scala/org/knora/webapi/slice/admin/api/GroupsEndpoints.scala b/webapi/src/main/scala/org/knora/webapi/slice/admin/api/GroupsEndpoints.scala index 7ff914bc00..4c71fd92cd 100644 --- a/webapi/src/main/scala/org/knora/webapi/slice/admin/api/GroupsEndpoints.scala +++ b/webapi/src/main/scala/org/knora/webapi/slice/admin/api/GroupsEndpoints.scala @@ -20,59 +20,61 @@ import org.knora.webapi.slice.admin.api.AdminPathVariables.groupIriPathVar import org.knora.webapi.slice.admin.api.GroupsRequests.GroupCreateRequest import org.knora.webapi.slice.admin.api.GroupsRequests.GroupStatusUpdateRequest import org.knora.webapi.slice.admin.api.GroupsRequests.GroupUpdateRequest -import org.knora.webapi.slice.admin.domain.model.GroupDescriptions -import org.knora.webapi.slice.admin.domain.model.GroupIri -import org.knora.webapi.slice.admin.domain.model.GroupName -import org.knora.webapi.slice.admin.domain.model.GroupSelfJoin -import org.knora.webapi.slice.admin.domain.model.GroupStatus -import org.knora.webapi.slice.admin.domain.model.KnoraProject.ProjectIri +import org.knora.webapi.slice.admin.domain.model.KnoraProject.* +import org.knora.webapi.slice.admin.domain.model.* import org.knora.webapi.slice.common.api.BaseEndpoints final case class GroupsEndpoints(baseEndpoints: BaseEndpoints) { private val base = "admin" / "groups" + private val groupGetResponse = + sprayJsonBody[GroupGetResponseADM].example(Examples.GroupEndpointsExample.groupGetResponseADM) + val getGroups = baseEndpoints.publicEndpoint.get .in(base) - .out(sprayJsonBody[GroupsGetResponseADM]) - .description("Returns all groups.") + .out(sprayJsonBody[GroupsGetResponseADM].example(Examples.GroupEndpointsExample.groupsGetResponseADM)) + .description("Return all groups.") val getGroupByIri = baseEndpoints.publicEndpoint.get .in(base / groupIriPathVar) - .out(sprayJsonBody[GroupGetResponseADM]) - .description("Returns a single group identified by IRI.") + .out(groupGetResponse) + .description("Return a single group identified by its IRI.") val getGroupMembers = baseEndpoints.securedEndpoint.get .in(base / groupIriPathVar / "members") - .out(sprayJsonBody[GroupMembersGetResponseADM]) - .description("Returns all members of a single group.") + .out(sprayJsonBody[GroupMembersGetResponseADM].example(Examples.GroupEndpointsExample.groupGetMembersResponse)) + .description("Return all members of a single group.") val postGroup = baseEndpoints.securedEndpoint.post .in(base) - .in(zioJsonBody[GroupCreateRequest]) - .out(sprayJsonBody[GroupGetResponseADM]) - .description("Creates a new group.") + .in(zioJsonBody[GroupCreateRequest].example(Examples.GroupEndpointsExample.groupCreateRequest)) + .out(groupGetResponse) + .name("Create new group") + .description( + "**Required permissions**: User must SystemAdmin or ProjectAdmin of the project the group is created in.", + ) val putGroup = baseEndpoints.securedEndpoint.put .in(base / groupIriPathVar) - .in(zioJsonBody[GroupUpdateRequest]) - .out(sprayJsonBody[GroupGetResponseADM]) - .description("Updates a group.") + .in(zioJsonBody[GroupUpdateRequest].example(Examples.GroupEndpointsExample.groupUpdateRequest)) + .out(groupGetResponse) + .description("Update a group's basic information.") val putGroupStatus = baseEndpoints.securedEndpoint.put .in(base / groupIriPathVar / "status") .in(zioJsonBody[GroupStatusUpdateRequest]) - .out(sprayJsonBody[GroupGetResponseADM]) + .out(groupGetResponse) .description("Updates a group's status.") val deleteGroup = baseEndpoints.securedEndpoint.delete .in(base / groupIriPathVar) - .out(sprayJsonBody[GroupGetResponseADM]) + .out(groupGetResponse) .description("Deletes a group by changing its status to 'false'.") - private val securedEndpoins = Seq(getGroupMembers, postGroup, putGroup, deleteGroup).map(_.endpoint) + private val securedEndpoints = Seq(getGroupMembers, postGroup, putGroup, putGroupStatus, deleteGroup).map(_.endpoint) - val endpoints: Seq[AnyEndpoint] = (Seq(getGroups, getGroupByIri) ++ securedEndpoins) + val endpoints: Seq[AnyEndpoint] = (Seq(getGroups, getGroupByIri) ++ securedEndpoints) .map(_.tag("Admin Groups")) } diff --git a/webapi/src/main/scala/org/knora/webapi/slice/admin/domain/model/User.scala b/webapi/src/main/scala/org/knora/webapi/slice/admin/domain/model/User.scala index 1887708dc2..df0e4835a5 100644 --- a/webapi/src/main/scala/org/knora/webapi/slice/admin/domain/model/User.scala +++ b/webapi/src/main/scala/org/knora/webapi/slice/admin/domain/model/User.scala @@ -51,7 +51,6 @@ final case class KnoraUser( * @param username The user's username (unique). * @param email The user's email address. * @param password The user's hashed password. - * @param token The API token. Can be used instead of email/password for authentication. * @param givenName The user's given name. * @param familyName The user's surname. * @param status The user's status.