Clean up OpenAPI scripts

controllers/AuthController.h

@@ -6,21 +6,75 @@ class AuthController : public drogon::HttpController<AuthController>
 {
   public:
     METHOD_LIST_BEGIN
+    /*
+     * openapi:
+     *   tags: Auth
+     *   summary: Register citizen
+     *   description: Creates a citizen account with personal data and password.
+     *   auth: public
+     *   body: json
+     *   response: Registration result.
+     */
     ADD_METHOD_TO(AuthController::registerCitizen,
                   "/api/v1/auth/register",
                   drogon::Post);
+    /*
+     * openapi:
+     *   tags: Auth
+     *   summary: Request OTP
+     *   description: Sends a one-time code by email through MailHog locally.
+     *   auth: public
+     *   body: json
+     *   response: OTP challenge result.
+     */
     ADD_METHOD_TO(AuthController::requestOtp,
                   "/api/v1/auth/otp/request",
                   drogon::Post);
+    /*
+     * openapi:
+     *   tags: Auth
+     *   summary: Verify OTP
+     *   description: Verifies an email OTP and creates an API token.
+     *   auth: public
+     *   body: json
+     *   response: Bearer token when verification succeeds.
+     */
     ADD_METHOD_TO(AuthController::verifyOtp,
                   "/api/v1/auth/otp/verify",
                   drogon::Post);
+    /*
+     * openapi:
+     *   tags: Auth
+     *   summary: Password login
+     *   description: Password-based login fallback for local development.
+     *   auth: public
+     *   body: json
+     *   response: Bearer token when credentials are valid.
+     */
     ADD_METHOD_TO(AuthController::loginWithPassword,
                   "/api/v1/auth/login/password",
                   drogon::Post);
+    /*
+     * openapi:
+     *   tags: Auth
+     *   summary: Change password
+     *   description: Changes the authenticated user's password.
+     *   auth: bearer
+     *   body: json
+     *   response: Password change result.
+     */
     ADD_METHOD_TO(AuthController::changePassword,
                   "/api/v1/auth/change-password",
                   drogon::Post);
+    /*
+     * openapi:
+     *   tags: Auth
+     *   summary: Current user
+     *   description: Returns the authenticated user's profile and permissions.
+     *   auth: bearer
+     *   body: none
+     *   response: Authenticated user context.
+     */
     ADD_METHOD_TO(AuthController::me, "/api/v1/me", drogon::Get);
     METHOD_LIST_END