[OpenAPI] Set tags for every operation

gmarciani · Nov 30, 2024 · 0cbb336 · 0cbb336
1 parent 814030d
commit 0cbb336
Show file tree

Hide file tree

Showing 23 changed files with 88 additions and 22 deletions.
diff --git a/server/src/main/kotlin/com/yawa/server/api/admin/SendMail.kt b/server/src/main/kotlin/com/yawa/server/api/admin/SendMail.kt
@@ -1,8 +1,10 @@
 package com.yawa.server.api.admin
 
+import com.yawa.server.constants.OpenApiTags.ADMINISTRATION
 import com.yawa.server.models.users.User
 import com.yawa.server.notifications.MailService
 import com.yawa.server.notifications.MailType
+import io.swagger.v3.oas.annotations.Operation
 import jakarta.validation.Valid
 import mu.KotlinLogging
 import org.springframework.beans.factory.annotation.Autowired
@@ -19,6 +21,7 @@ class SendMail(
     @Autowired val mailService: MailService,
 ) {
 
+    @Operation(tags = [ADMINISTRATION])
     @PostMapping("/admin/mail", produces = [MediaType.APPLICATION_JSON_VALUE])
     fun sendMail(
         @Valid @RequestBody request: SendMailRequest,

diff --git a/server/src/main/kotlin/com/yawa/server/api/auth/Login.kt b/server/src/main/kotlin/com/yawa/server/api/auth/Login.kt
@@ -1,8 +1,10 @@
 package com.yawa.server.api.auth
 
+import com.yawa.server.constants.OpenApiTags.AUTHENTICATION
 import com.yawa.server.security.authentication.AuthenticationService
 import com.yawa.server.validators.Password
 import com.yawa.server.validators.Username
+import io.swagger.v3.oas.annotations.Operation
 import jakarta.validation.Valid
 import mu.KotlinLogging
 import org.springframework.beans.factory.annotation.Autowired
@@ -19,6 +21,7 @@ class Login(
     @Autowired val authenticationService: AuthenticationService,
 ) {
 
+    @Operation(tags = [AUTHENTICATION])
     @PostMapping("/auth/login", produces = [MediaType.APPLICATION_JSON_VALUE])
     fun login(
         @Valid @RequestBody request: LoginRequest,

diff --git a/server/src/main/kotlin/com/yawa/server/api/auth/Logout.kt b/server/src/main/kotlin/com/yawa/server/api/auth/Logout.kt
@@ -1,6 +1,8 @@
 package com.yawa.server.api.auth
 
+import com.yawa.server.constants.OpenApiTags.AUTHENTICATION
 import com.yawa.server.models.users.User
+import io.swagger.v3.oas.annotations.Operation
 import mu.KotlinLogging
 import org.springframework.http.MediaType
 import org.springframework.security.core.context.SecurityContextHolder
@@ -12,6 +14,7 @@ private val log = KotlinLogging.logger {}
 @RestController
 class Logout {
 
+    @Operation(tags = [AUTHENTICATION])
     @PostMapping("/auth/logout", produces = [MediaType.APPLICATION_JSON_VALUE])
     fun logout(): LogoutResponse {
         log.info("Processing request")

diff --git a/server/src/main/kotlin/com/yawa/server/api/auth/RefreshAuthentication.kt b/server/src/main/kotlin/com/yawa/server/api/auth/RefreshAuthentication.kt
@@ -1,6 +1,8 @@
 package com.yawa.server.api.auth
 
+import com.yawa.server.constants.OpenApiTags.AUTHENTICATION
 import com.yawa.server.security.authentication.AuthenticationService
+import io.swagger.v3.oas.annotations.Operation
 import mu.KotlinLogging
 import org.springframework.beans.factory.annotation.Autowired
 import org.springframework.http.MediaType
@@ -17,6 +19,7 @@ class RefreshAuthentication(
     @Autowired val authenticationService: AuthenticationService,
 ) {
 
+    @Operation(tags = [AUTHENTICATION])
     @GetMapping("/auth/{username}/tokens", produces = [MediaType.APPLICATION_JSON_VALUE])
     fun refreshAuthentication(
         @PathVariable username: String,

diff --git a/server/src/main/kotlin/com/yawa/server/api/simple/GetGreetings.kt b/server/src/main/kotlin/com/yawa/server/api/simple/GetGreetings.kt
@@ -1,6 +1,8 @@
 package com.yawa.server.api.simple
 
+import com.yawa.server.constants.OpenApiTags.SIMPLE
 import com.yawa.server.models.users.User
+import io.swagger.v3.oas.annotations.Operation
 import mu.KotlinLogging
 import org.springframework.http.MediaType
 import org.springframework.security.authentication.AnonymousAuthenticationToken
@@ -13,6 +15,7 @@ private val log = KotlinLogging.logger {}
 @RestController
 class GetGreetings {
 
+    @Operation(tags = [SIMPLE])
     @GetMapping("/simple/greetings", produces = [MediaType.APPLICATION_JSON_VALUE])
     fun getGreetings(): GetAuthenticatedHelloResponse {
         log.info("Processing request")

diff --git a/server/src/main/kotlin/com/yawa/server/api/simple/GetOutcome.kt b/server/src/main/kotlin/com/yawa/server/api/simple/GetOutcome.kt
@@ -1,9 +1,11 @@
 package com.yawa.server.api.simple
 
+import com.yawa.server.constants.OpenApiTags.SIMPLE
 import com.yawa.server.exceptions.NotAuthorizedException
 import com.yawa.server.exceptions.ResourceNotFoundException
 import com.yawa.server.exceptions.YawaBadRequestException
 import com.yawa.server.exceptions.YawaInternalException
+import io.swagger.v3.oas.annotations.Operation
 import mu.KotlinLogging
 import org.springframework.http.MediaType
 import org.springframework.web.bind.annotation.GetMapping
@@ -16,6 +18,7 @@ private val log = KotlinLogging.logger {}
 @RestController
 class GetOutcome {
 
+    @Operation(tags = [SIMPLE])
     @GetMapping("/simple/outcome", produces = [MediaType.APPLICATION_JSON_VALUE])
     fun getOutcome(
         @RequestParam outcome: Outcome,

diff --git a/server/src/main/kotlin/com/yawa/server/api/users/creation/ActivateUser.kt b/server/src/main/kotlin/com/yawa/server/api/users/creation/ActivateUser.kt
@@ -1,10 +1,12 @@
 package com.yawa.server.api.users.creation
 
+import com.yawa.server.constants.OpenApiTags.USERS
 import com.yawa.server.models.tokens.TokenAction
 import com.yawa.server.notifications.MailService
 import com.yawa.server.notifications.MailType
 import com.yawa.server.security.tokens.ActionTokenService
 import com.yawa.server.services.UserService
+import io.swagger.v3.oas.annotations.Operation
 import mu.KotlinLogging
 import org.springframework.beans.factory.annotation.Autowired
 import org.springframework.http.MediaType
@@ -22,6 +24,7 @@ class ActivateUser(
     @Autowired val mailService: MailService,
 ) {
 
+    @Operation(tags = [USERS])
     @PostMapping("/users/{username}/activation", produces = [MediaType.APPLICATION_JSON_VALUE])
     fun activateUser(
         @PathVariable username: String,

diff --git a/server/src/main/kotlin/com/yawa/server/api/users/creation/CreateUser.kt b/server/src/main/kotlin/com/yawa/server/api/users/creation/CreateUser.kt
@@ -1,5 +1,6 @@
 package com.yawa.server.api.users.creation
 
+import com.yawa.server.constants.OpenApiTags.USERS
 import com.yawa.server.datastore.repositories.UserRepository
 import com.yawa.server.exceptions.DuplicatedResourceException
 import com.yawa.server.models.tokens.TokenAction
@@ -11,6 +12,7 @@ import com.yawa.server.services.UserService
 import com.yawa.server.validators.Email
 import com.yawa.server.validators.Password
 import com.yawa.server.validators.Username
+import io.swagger.v3.oas.annotations.Operation
 import jakarta.validation.Valid
 import mu.KotlinLogging
 import org.springframework.beans.factory.annotation.Autowired
@@ -30,6 +32,7 @@ class CreateUser(
     @Autowired val mailService: MailService,
 ) {
 
+    @Operation(tags = [USERS])
     @PostMapping("/users", produces = [MediaType.APPLICATION_JSON_VALUE])
     fun createUser(
         @Valid @RequestBody request: CreateUserRequest,

diff --git a/server/src/main/kotlin/com/yawa/server/api/users/creation/SendUserActivationToken.kt b/server/src/main/kotlin/com/yawa/server/api/users/creation/SendUserActivationToken.kt
@@ -1,11 +1,13 @@
 package com.yawa.server.api.users.creation
 
+import com.yawa.server.constants.OpenApiTags.USERS
 import com.yawa.server.exceptions.UserAlreadyEnabledException
 import com.yawa.server.models.tokens.TokenAction
 import com.yawa.server.notifications.MailService
 import com.yawa.server.notifications.MailType
 import com.yawa.server.security.tokens.ActionTokenService
 import com.yawa.server.services.UserService
+import io.swagger.v3.oas.annotations.Operation
 import mu.KotlinLogging
 import org.springframework.beans.factory.annotation.Autowired
 import org.springframework.http.MediaType
@@ -23,6 +25,7 @@ class SendUserActivationToken(
     @Autowired val mailService: MailService,
 ) {
 
+    @Operation(tags = [USERS])
     @GetMapping("/users/{username}/tokens/activation", produces = [MediaType.APPLICATION_JSON_VALUE])
     @PreAuthorize("authentication.principal.username == #username || hasRole('ROLE_ADMIN')")
     fun sendUserActivationToken(

diff --git a/server/src/main/kotlin/com/yawa/server/api/users/deletion/DeleteUser.kt b/server/src/main/kotlin/com/yawa/server/api/users/deletion/DeleteUser.kt
@@ -1,10 +1,12 @@
 package com.yawa.server.api.users.deletion
 
+import com.yawa.server.constants.OpenApiTags.USERS
 import com.yawa.server.models.tokens.TokenAction
 import com.yawa.server.notifications.MailService
 import com.yawa.server.notifications.MailType
 import com.yawa.server.security.tokens.ActionTokenService
 import com.yawa.server.services.UserService
+import io.swagger.v3.oas.annotations.Operation
 import mu.KotlinLogging
 import org.springframework.beans.factory.annotation.Autowired
 import org.springframework.http.MediaType
@@ -23,6 +25,7 @@ class DeleteUser(
     @Autowired val mailService: MailService,
 ) {
 
+    @Operation(tags = [USERS])
     @DeleteMapping("/users/{username}", produces = [MediaType.APPLICATION_JSON_VALUE])
     @PreAuthorize("authentication.principal.username == #username || hasRole('ROLE_ADMIN')")
     fun deleteUser(

diff --git a/server/src/main/kotlin/com/yawa/server/api/users/deletion/SendUserDeletionToken.kt b/server/src/main/kotlin/com/yawa/server/api/users/deletion/SendUserDeletionToken.kt
@@ -1,10 +1,12 @@
 package com.yawa.server.api.users.deletion
 
+import com.yawa.server.constants.OpenApiTags.USERS
 import com.yawa.server.models.tokens.TokenAction
 import com.yawa.server.notifications.MailService
 import com.yawa.server.notifications.MailType
 import com.yawa.server.security.tokens.ActionTokenService
 import com.yawa.server.services.UserService
+import io.swagger.v3.oas.annotations.Operation
 import mu.KotlinLogging
 import org.springframework.beans.factory.annotation.Autowired
 import org.springframework.http.MediaType
@@ -22,6 +24,7 @@ class SendUserDeletionToken(
     @Autowired val mailService: MailService,
 ) {
 
+    @Operation(tags = [USERS])
     @GetMapping("/users/{username}/tokens/deletion", produces = [MediaType.APPLICATION_JSON_VALUE])
     @PreAuthorize("authentication.principal.username == #username || hasRole('ROLE_ADMIN')")
     fun sendUserDeletionToken(

diff --git a/server/src/main/kotlin/com/yawa/server/api/users/password/ResetPassword.kt b/server/src/main/kotlin/com/yawa/server/api/users/password/ResetPassword.kt
@@ -1,10 +1,12 @@
 package com.yawa.server.api.users.password
 
+import com.yawa.server.constants.OpenApiTags.USERS
 import com.yawa.server.models.tokens.TokenAction
 import com.yawa.server.notifications.MailService
 import com.yawa.server.notifications.MailType
 import com.yawa.server.security.tokens.ActionTokenService
 import com.yawa.server.services.UserService
+import io.swagger.v3.oas.annotations.Operation
 import mu.KotlinLogging
 import org.springframework.beans.factory.annotation.Autowired
 import org.springframework.http.MediaType
@@ -22,6 +24,7 @@ class ResetPassword(
     @Autowired val mailService: MailService,
 ) {
 
+    @Operation(tags = [USERS])
     @PatchMapping("/users/{username}/password", produces = [MediaType.APPLICATION_JSON_VALUE])
     fun resetPassword(
         @PathVariable username: String,

diff --git a/server/src/main/kotlin/com/yawa/server/api/users/password/SendPasswordResetToken.kt b/server/src/main/kotlin/com/yawa/server/api/users/password/SendPasswordResetToken.kt
@@ -1,10 +1,12 @@
 package com.yawa.server.api.users.password
 
+import com.yawa.server.constants.OpenApiTags.USERS
 import com.yawa.server.models.tokens.TokenAction
 import com.yawa.server.notifications.MailService
 import com.yawa.server.notifications.MailType
 import com.yawa.server.security.tokens.ActionTokenService
 import com.yawa.server.services.UserService
+import io.swagger.v3.oas.annotations.Operation
 import mu.KotlinLogging
 import org.springframework.beans.factory.annotation.Autowired
 import org.springframework.http.MediaType
@@ -21,6 +23,7 @@ class SendPasswordResetToken(
     @Autowired val mailService: MailService,
 ) {
 
+    @Operation(tags = [USERS])
     @GetMapping("/users/{username}/tokens/password", produces = [MediaType.APPLICATION_JSON_VALUE])
     fun sendPasswordResetToken(
         @PathVariable username: String,

diff --git a/server/src/main/kotlin/com/yawa/server/api/users/profile/GetUserProfile.kt b/server/src/main/kotlin/com/yawa/server/api/users/profile/GetUserProfile.kt
@@ -1,8 +1,10 @@
 package com.yawa.server.api.users.profile
 
+import com.yawa.server.constants.OpenApiTags.USERS
 import com.yawa.server.datastore.repositories.UserRepository
 import com.yawa.server.exceptions.ResourceNotFoundException
 import com.yawa.server.models.users.UserProfile
+import io.swagger.v3.oas.annotations.Operation
 import mu.KotlinLogging
 import org.springframework.beans.factory.annotation.Autowired
 import org.springframework.http.MediaType
@@ -17,6 +19,7 @@ class GetUserProfile(
     @Autowired val userRepository: UserRepository,
 ) {
 
+    @Operation(tags = [USERS])
     @GetMapping("/users/{username}/profile", produces = [MediaType.APPLICATION_JSON_VALUE])
     fun getUserProfile(
         @PathVariable username: String,

diff --git a/server/src/main/kotlin/com/yawa/server/api/users/profile/UpdateUserProfile.kt b/server/src/main/kotlin/com/yawa/server/api/users/profile/UpdateUserProfile.kt
@@ -1,10 +1,12 @@
 package com.yawa.server.api.users.profile
 
+import com.yawa.server.constants.OpenApiTags.USERS
 import com.yawa.server.datastore.repositories.UserProfileRepository
 import com.yawa.server.datastore.repositories.UserRepository
 import com.yawa.server.exceptions.ResourceNotFoundException
 import com.yawa.server.models.users.Gender
 import com.yawa.server.models.users.UserProfile
+import io.swagger.v3.oas.annotations.Operation
 import jakarta.validation.Valid
 import mu.KotlinLogging
 import org.springframework.beans.factory.annotation.Autowired
@@ -24,6 +26,7 @@ class UpdateUserProfile(
     @Autowired val userProfileRepository: UserProfileRepository,
 ) {
 
+    @Operation(tags = [USERS])
     @PatchMapping("/users/{username}/profile", produces = [MediaType.APPLICATION_JSON_VALUE])
     @PreAuthorize("authentication.principal.username == #username || hasRole('ROLE_ADMIN')")
     fun updateUserProfile(

diff --git a/server/src/main/kotlin/com/yawa/server/api/users/profile/picture/DeleteUserPicture.kt b/server/src/main/kotlin/com/yawa/server/api/users/profile/picture/DeleteUserPicture.kt
@@ -1,6 +1,8 @@
 package com.yawa.server.api.users.profile.picture
 
+import com.yawa.server.constants.OpenApiTags.USERS
 import com.yawa.server.services.UserService
+import io.swagger.v3.oas.annotations.Operation
 import mu.KotlinLogging
 import org.springframework.beans.factory.annotation.Autowired
 import org.springframework.http.MediaType
@@ -16,6 +18,7 @@ class DeleteUserPicture(
     @Autowired val userService: UserService,
 ) {
 
+    @Operation(tags = [USERS])
     @DeleteMapping("/users/{username}/profile/picture", produces = [MediaType.APPLICATION_JSON_VALUE])
     @PreAuthorize("authentication.principal.username == #username || hasRole('ROLE_ADMIN')")
     fun deleteUserPicture(

diff --git a/server/src/main/kotlin/com/yawa/server/api/users/profile/picture/UpdateUserPicture.kt b/server/src/main/kotlin/com/yawa/server/api/users/profile/picture/UpdateUserPicture.kt
@@ -1,6 +1,8 @@
 package com.yawa.server.api.users.profile.picture
 
+import com.yawa.server.constants.OpenApiTags.USERS
 import com.yawa.server.services.UserService
+import io.swagger.v3.oas.annotations.Operation
 import mu.KotlinLogging
 import org.springframework.beans.factory.annotation.Autowired
 import org.springframework.http.MediaType
@@ -18,6 +20,7 @@ class UpdateUserPicture(
     @Autowired val userService: UserService,
 ) {
 
+    @Operation(tags = [USERS])
     @PatchMapping("/users/{username}/profile/picture", produces = [MediaType.APPLICATION_JSON_VALUE])
     @PreAuthorize("authentication.principal.username == #username || hasRole('ROLE_ADMIN')")
     fun updateUserPicture(

diff --git a/server/src/main/kotlin/com/yawa/server/api/users/settings/GetUserSettings.kt b/server/src/main/kotlin/com/yawa/server/api/users/settings/GetUserSettings.kt
@@ -1,8 +1,10 @@
 package com.yawa.server.api.users.settings
 
+import com.yawa.server.constants.OpenApiTags.USERS
 import com.yawa.server.datastore.repositories.UserRepository
 import com.yawa.server.exceptions.ResourceNotFoundException
 import com.yawa.server.models.users.UserSettings
+import io.swagger.v3.oas.annotations.Operation
 import mu.KotlinLogging
 import org.springframework.beans.factory.annotation.Autowired
 import org.springframework.http.MediaType
@@ -18,6 +20,7 @@ class GetUserSettings(
     @Autowired val userRepository: UserRepository,
 ) {
 
+    @Operation(tags = [USERS])
     @GetMapping("/users/{username}/settings", produces = [MediaType.APPLICATION_JSON_VALUE])
     @PreAuthorize("authentication.principal.username == #username || hasRole('ROLE_ADMIN')")
     fun getUserSettings(

diff --git a/server/src/main/kotlin/com/yawa/server/api/users/settings/UpdateUserSettings.kt b/server/src/main/kotlin/com/yawa/server/api/users/settings/UpdateUserSettings.kt
@@ -1,9 +1,11 @@
 package com.yawa.server.api.users.settings
 
+import com.yawa.server.constants.OpenApiTags.USERS
 import com.yawa.server.datastore.repositories.UserRepository
 import com.yawa.server.datastore.repositories.UserSettingsRepository
 import com.yawa.server.exceptions.ResourceNotFoundException
 import com.yawa.server.models.users.UserSettings
+import io.swagger.v3.oas.annotations.Operation
 import jakarta.validation.Valid
 import mu.KotlinLogging
 import org.springframework.beans.factory.annotation.Autowired
@@ -22,6 +24,7 @@ class UpdateUserSettings(
     @Autowired val userSettingsRepository: UserSettingsRepository,
 ) {
 
+    @Operation(tags = [USERS])
     @PatchMapping("/users/{username}/settings", produces = [MediaType.APPLICATION_JSON_VALUE])
     @PreAuthorize("authentication.principal.username == #username || hasRole('ROLE_ADMIN')")
     fun updateUserSettings(

diff --git a/server/src/main/kotlin/com/yawa/server/config/OpenApiConfig.kt b/server/src/main/kotlin/com/yawa/server/config/OpenApiConfig.kt
@@ -63,7 +63,7 @@ class OpenApiConfig {
                         Operation()
                             .summary("Actuator web endpoint 'docs/openapi'")
                             .operationId("openapi")
-                            .tags(listOf("Actuator"))
+                            .tags(listOf("Documentation"))
                             .responses(
                                 ApiResponses().addApiResponse(
                                     "200",

diff --git a/server/src/main/kotlin/com/yawa/server/constants/OpenApiTags.kt b/server/src/main/kotlin/com/yawa/server/constants/OpenApiTags.kt
@@ -0,0 +1,8 @@
+package com.yawa.server.constants
+
+object OpenApiTags {
+    const val ADMINISTRATION = "Administration"
+    const val AUTHENTICATION = "Authentication"
+    const val SIMPLE = "Simple"
+    const val USERS = "Users"
+}
diff --git a/server/src/main/resources/application.yaml b/server/src/main/resources/application.yaml
@@ -152,6 +152,7 @@ springdoc:
     enabled: true
     path: /docs/openapi-ui.html
     layout: BaseLayout
+    display-operation-id: true
   show-actuator: true
   remove-broken-reference-definitions: true
   writer-with-order-by-keys: true