chore: tidy swagger comments;

feat: password reset models;
feat: verification code validator

backend/docs/swagger.yaml

@@ -27,6 +27,49 @@ definitions:
       refresh_token:
         type: string
     type: object
+  models.PasswordResetBeginRequest:
+    properties:
+      email:
+        type: string
+    required:
+    - email
+    type: object
+  models.PasswordResetCompleteRequest:
+    properties:
+      email:
+        type: string
+      log_out_accounts:
+        type: boolean
+      password:
+        type: string
+      verification_code:
+        type: string
+    required:
+    - email
+    - password
+    - verification_code
+    type: object
+  models.PasswordResetCompleteResponse:
+    properties:
+      access_token:
+        type: string
+      refresh_token:
+        type: string
+    type: object
+  models.RefreshRequest:
+    properties:
+      refresh_token:
+        type: string
+    required:
+    - refresh_token
+    type: object
+  models.RefreshResponse:
+    properties:
+      access_token:
+        type: string
+      refresh_token:
+        type: string
+    type: object
   models.RegistrationBeginRequest:
     properties:
       email:
@@ -36,6 +79,7 @@ definitions:
       username:
         type: string
     required:
+    - email
     - password
     - username
     type: object
@@ -86,7 +130,7 @@ paths:
       consumes:
       - application/json
       parameters:
-      - description: desc
+      - description: ' '
         in: body
         name: request
         required: true
@@ -96,9 +140,11 @@ paths:
       - application/json
       responses:
         "200":
-          description: desc
+          description: ' '
           schema:
             $ref: '#/definitions/models.LoginResponse'
+        "403":
+          description: Invalid login credentials
       summary: Acquire tokens via login credentials (and 2FA code if needed)
       tags:
       - Auth
@@ -106,9 +152,20 @@ paths:
     post:
       consumes:
       - application/json
+      parameters:
+      - description: ' '
+        in: body
+        name: request
+        required: true
+        schema:
+          $ref: '#/definitions/models.PasswordResetBeginRequest'
       produces:
       - application/json
-      responses: {}
+      responses:
+        "200":
+          description: Reset code sent to the email if it is attached to an account
+        "429":
+          description: Too many recent requests for this email
       summary: Request password reset email
       tags:
       - Auth
@@ -116,20 +173,45 @@ paths:
     post:
       consumes:
       - application/json
+      parameters:
+      - description: ' '
+        in: body
+        name: request
+        required: true
+        schema:
+          $ref: '#/definitions/models.PasswordResetCompleteRequest'
       produces:
       - application/json
-      responses: {}
-      summary: Complete password reset with email code and provide 2FA code or backup
-        code if needed
+      responses:
+        "200":
+          description: ' '
+          schema:
+            $ref: '#/definitions/models.PasswordResetCompleteResponse'
+        "403":
+          description: Wrong verification code or username
+      summary: Complete password reset via email code
       tags:
       - Auth
   /auth/refresh:
     post:
       consumes:
       - application/json
+      parameters:
+      - description: ' '
+        in: body
+        name: request
+        required: true
+        schema:
+          $ref: '#/definitions/models.RefreshRequest'
       produces:
       - application/json
-      responses: {}
+      responses:
+        "200":
+          description: ' '
+          schema:
+            $ref: '#/definitions/models.RefreshResponse'
+        "401":
+          description: Invalid refresh token
       summary: Receive new tokens via refresh token
       tags:
       - Auth
@@ -138,7 +220,7 @@ paths:
       consumes:
       - application/json
       parameters:
-      - description: desc
+      - description: ' '
         in: body
         name: request
         required: true
@@ -151,6 +233,8 @@ paths:
           description: Account is created and awaiting verification
         "409":
           description: Username or email is already taken
+        "429":
+          description: Too many recent registration attempts for this email
       summary: Register an account
       tags:
       - Auth
@@ -159,7 +243,7 @@ paths:
       consumes:
       - application/json
       parameters:
-      - description: desc
+      - description: ' '
         in: body
         name: request
         required: true
@@ -169,9 +253,11 @@ paths:
       - application/json
       responses:
         "200":
-          description: desc
+          description: ' '
           schema:
             $ref: '#/definitions/models.RegistrationCompleteResponse'
+        "403":
+          description: Invalid email or verification code
       summary: Confirm with code, finish creating the account
       tags:
       - Auth