Clean up OpenAPI scripts

controllers/AdminController.h

@@ -6,23 +6,113 @@ class AdminController : public drogon::HttpController<AdminController>
 {
   public:
     METHOD_LIST_BEGIN
+    /*
+     * openapi:
+     *   tags: Admin
+     *   summary: List categories
+     *   description: Lists active report categories.
+     *   auth: bearer
+     *   body: none
+     *   response: Report category list.
+     */
     ADD_METHOD_TO(AdminController::listCategories,
                   "/api/v1/admin/categories",
                   drogon::Get);
+    /*
+     * openapi:
+     *   tags: Admin
+     *   summary: Create category
+     *   description: Creates a report category.
+     *   auth: bearer
+     *   body: json
+     *   response: Created category result.
+     */
     ADD_METHOD_TO(AdminController::createCategory,
                   "/api/v1/admin/categories",
                   drogon::Post);
+    /*
+     * openapi:
+     *   tags: Admin
+     *   summary: List areas
+     *   description: Lists configured municipal areas.
+     *   auth: bearer
+     *   body: none
+     *   response: Area list.
+     */
     ADD_METHOD_TO(AdminController::listAreas, "/api/v1/admin/areas", drogon::Get);
+    /*
+     * openapi:
+     *   tags: Admin
+     *   summary: Create area
+     *   description: Creates a municipal area with GeoJSON boundary.
+     *   auth: bearer
+     *   body: json
+     *   response: Created area result.
+     */
     ADD_METHOD_TO(AdminController::createArea, "/api/v1/admin/areas", drogon::Post);
+    /*
+     * openapi:
+     *   tags: Admin
+     *   summary: List teams
+     *   description: Lists intervention teams.
+     *   auth: bearer
+     *   body: none
+     *   response: Team list.
+     */
     ADD_METHOD_TO(AdminController::listTeams, "/api/v1/admin/teams", drogon::Get);
+    /*
+     * openapi:
+     *   tags: Admin
+     *   summary: Create team
+     *   description: Creates an intervention team.
+     *   auth: bearer
+     *   body: json
+     *   response: Created team result.
+     */
     ADD_METHOD_TO(AdminController::createTeam, "/api/v1/admin/teams", drogon::Post);
+    /*
+     * openapi:
+     *   tags: Admin
+     *   summary: Overview stats
+     *   description: Returns report statistics for administration dashboards.
+     *   auth: bearer
+     *   body: none
+     *   response: Aggregated report statistics.
+     */
     ADD_METHOD_TO(AdminController::overviewStats,
                   "/api/v1/admin/stats/overview",
                   drogon::Get);
+    /*
+     * openapi:
+     *   tags: Admin
+     *   summary: List users
+     *   description: Lists platform users with role information.
+     *   auth: bearer
+     *   body: none
+     *   response: User list.
+     */
     ADD_METHOD_TO(AdminController::listUsers, "/api/v1/admin/users", drogon::Get);
+    /*
+     * openapi:
+     *   tags: Admin
+     *   summary: Update user roles
+     *   description: Replaces the roles assigned to a user.
+     *   auth: bearer
+     *   body: json
+     *   response: Role update result.
+     */
     ADD_METHOD_TO(AdminController::updateUserRoles,
                   "/api/v1/admin/users/{1}/roles",
                   drogon::Patch);
+    /*
+     * openapi:
+     *   tags: Admin
+     *   summary: Ban or unban user
+     *   description: Updates a user's banned flag.
+     *   auth: bearer
+     *   body: json
+     *   response: Ban update result.
+     */
     ADD_METHOD_TO(AdminController::updateUserBan,
                   "/api/v1/admin/users/{1}/ban",
                   drogon::Patch);
@@ -61,4 +151,3 @@ class AdminController : public drogon::HttpController<AdminController>
         std::function<void(const drogon::HttpResponsePtr &)> &&callback,
         long long userId);
 };
-