[+] API documentation

src/main/java/ext/Ext.kt

@@ -21,6 +21,13 @@ typealias API = RequestMapping
 typealias Str = String
 typealias Bool = Boolean
 
+@Target(AnnotationTarget.CLASS, AnnotationTarget.FUNCTION)
+@Retention(AnnotationRetention.RUNTIME)
+annotation class Doc(
+    val desc: String,
+    val ret: String = ""
+)
+
 // Make it easier to throw a ResponseStatusException
 operator fun HttpStatus.invoke(message: String? = null): Nothing = throw ApiException(value(), message ?: this.reasonPhrase)
 operator fun Int.minus(message: String): Nothing = throw ApiException(this, message)

src/main/java/icu/samnyan/aqua/net/CardController.kt

@@ -23,6 +23,7 @@ class CardController(
     val props: AquaNetProps
 ) {
     @API("/summary")
+    @Doc("Get a summary of the card, including the user's name, rating, and last login date.", "Summary of the card")
     suspend fun summary(@RP cardId: Str): Any
     {
         // DO NOT CHANGE THIS ERROR MESSAGE - The frontend uses it to detect if the card is not found
@@ -45,6 +46,7 @@ class CardController(
      * @param migrate Things to migrate, stored as a comma-separated list of game IDs (e.g. "maimai2,chusan")
      */
     @API("/link")
+    @Doc("Bind a card to the user. This action will migrate selected data from the card to the user's ghost card.", "Success message")
     suspend fun link(@RP token: Str, @RP cardId: Str, @RP migrate: Str) = jwt.auth(token) { u ->
         // Check if the user's card limit is reached
         if (u.cards.size >= props.linkCardLimit) 400 - "Card limit reached"
@@ -78,6 +80,7 @@ class CardController(
     }
 
     @API("/unlink")
+    @Doc("Unbind a card from the user. No data will be migrated during this action.", "Success message")
     suspend fun unlink(@RP token: Str, @RP cardId: Str) = jwt.auth(token) { u ->
         // Try to look up the card
         val card = cardService.tryLookup(cardId) ?: (404 - "Card not found")

src/main/java/icu/samnyan/aqua/net/UserRegistrar.kt

@@ -37,10 +37,8 @@ class UserRegistrar(
         const val cardExtIdEnd = 4294967295
     }
 
-    /**
-     * Register a new user
-     */
     @API("/register")
+    @Doc("Register a new user. This will also create a ghost card for the user and send a confirmation email.", "Success message")
     suspend fun register(
         @RP username: Str, @RP email: Str, @RP password: Str, @RP turnstile: Str,
         request: HttpServletRequest
@@ -86,6 +84,7 @@ class UserRegistrar(
     }
 
     @API("/login")
+    @Doc("Login with email/username and password. This will also check if the email is verified and send another confirmation", "JWT token")
     suspend fun login(
         @RP email: Str, @RP password: Str, @RP turnstile: Str,
         request: HttpServletRequest
@@ -130,6 +129,7 @@ class UserRegistrar(
     }
 
     @API("/confirm-email")
+    @Doc("Confirm email address with a token sent through email to the user.", "Success message")
     suspend fun confirmEmail(@RP token: Str): Any {
         // Find the confirmation
         val confirmation = async { confirmationRepo.findByToken(token) }
@@ -147,9 +147,11 @@ class UserRegistrar(
     }
 
     @API("/me")
+    @Doc("Get the information of the current logged-in user.", "User information")
     suspend fun getUser(@RP token: Str) = jwt.auth(token)
 
     @API("/setting")
+    @Doc("Validate and set a user setting field.", "Success message")
     suspend fun setting(@RP token: Str, @RP key: Str, @RP value: Str) = jwt.auth(token) { u ->
         // Check if the key is a settable field
         val field = SETTING_FIELDS.find { it.name == key } ?: (400 - "Invalid setting")