Document new endpoints

NIAEFEUP · Jul 13, 2023 · 1977986 · 1977986
1 parent 95b8960
commit 1977986
Show file tree

Hide file tree

Showing 2 changed files with 37 additions and 4 deletions.
diff --git a/src/test/kotlin/pt/up/fe/ni/website/backend/controller/AuthControllerTest.kt b/src/test/kotlin/pt/up/fe/ni/website/backend/controller/AuthControllerTest.kt
@@ -1,6 +1,7 @@
 package pt.up.fe.ni.website.backend.controller
 
 import com.epages.restdocs.apispec.HeaderDescriptorWithType
+import com.epages.restdocs.apispec.ResourceDocumentation
 import com.epages.restdocs.apispec.ResourceDocumentation.headerWithName
 import com.fasterxml.jackson.databind.ObjectMapper
 import jakarta.transaction.Transactional
@@ -35,6 +36,7 @@ import pt.up.fe.ni.website.backend.utils.annotations.NestedTest
 import pt.up.fe.ni.website.backend.utils.documentation.payloadschemas.model.PayloadAuthCheck
 import pt.up.fe.ni.website.backend.utils.documentation.payloadschemas.model.PayloadAuthNew
 import pt.up.fe.ni.website.backend.utils.documentation.payloadschemas.model.PayloadAuthRefresh
+import pt.up.fe.ni.website.backend.utils.documentation.payloadschemas.model.PayloadPermissionCheck
 import pt.up.fe.ni.website.backend.utils.documentation.utils.MockMVCExtension.Companion.andDocument
 import pt.up.fe.ni.website.backend.utils.documentation.utils.MockMVCExtension.Companion.andDocumentErrorResponse
 import pt.up.fe.ni.website.backend.utils.documentation.utils.ModelDocumentation
@@ -246,6 +248,17 @@ class AuthControllerTest @Autowired constructor(
             repository.save(testAccount)
         }
 
+        val documentation: ModelDocumentation = PayloadPermissionCheck()
+        val globalParameters = listOf(
+            ResourceDocumentation.parameterWithName("permission")
+                .description("String representation of the permission to test")
+        )
+        val perActivityParameters = listOf(
+            ResourceDocumentation.parameterWithName("activityId").description("Id of the activity"),
+            ResourceDocumentation.parameterWithName("permission")
+                .description("String representation of the permission to test")
+        )
+
         @Test
         fun `should fail when user doesn't have global permission`() {
             mockMvc.post("/auth/new") {
@@ -259,7 +272,7 @@ class AuthControllerTest @Autowired constructor(
                             Permission.SUPERUSER
                         }"
                     ).header("Authorization", "Bearer $accessToken")
-                ).andExpect(status().isForbidden)
+                ).andExpect(status().isForbidden).andDocumentErrorResponse(documentation)
             }
         }
 
@@ -276,7 +289,14 @@ class AuthControllerTest @Autowired constructor(
                             testPermissions[0]
                         }"
                     ).header("Authorization", "Bearer $accessToken")
-                ).andExpect(status().isOk)
+                ).andExpect(status().isOk).andDocument(
+                    documentation,
+                    "Check global user permission",
+                    "This endpoint succeeds whether the user has the given permission in one of their roles",
+                    checkAuthHeaders,
+                    emptyList(),
+                    globalParameters
+                )
             }
         }
 
@@ -293,7 +313,7 @@ class AuthControllerTest @Autowired constructor(
                             Permission.DELETE_ACTIVITY
                         }"
                     ).header("Authorization", "Bearer $accessToken")
-                ).andExpect(status().isForbidden)
+                ).andExpect(status().isForbidden).andDocumentErrorResponse(documentation)
             }
         }
 
@@ -310,7 +330,14 @@ class AuthControllerTest @Autowired constructor(
                             Permission.EDIT_ACTIVITY
                         }"
                     ).header("Authorization", "Bearer $accessToken")
-                ).andExpect(status().isOk)
+                ).andExpect(status().isOk).andDocument(
+                    documentation,
+                    "Check per activity user permission",
+                    "This endpoint succeeds whether the user has the given permission upon an activity",
+                    checkAuthHeaders,
+                    emptyList(),
+                    perActivityParameters
+                )
             }
         }
     }

diff --git a/...otlin/pt/up/fe/ni/website/backend/utils/documentation/payloadschemas/model/PayloadAuth.kt b/...otlin/pt/up/fe/ni/website/backend/utils/documentation/payloadschemas/model/PayloadAuth.kt
@@ -68,3 +68,9 @@ class PayloadAuthCheck : ModelDocumentation(
         )
     ).addFieldsBeneathPath("authenticated_user", PayloadAccount().payload.documentedJSONFields, addResponse = true)
 )
+
+class PayloadPermissionCheck : ModelDocumentation(
+    Tag.AUTH.name.lowercase() + "-permission-check",
+    Tag.AUTH,
+    mutableListOf()
+)