From ceadf420485b4a03f8d15b2525b19ff4d441c87a Mon Sep 17 00:00:00 2001 From: Nathan Coad Date: Thu, 22 Jan 2026 12:52:28 +1100 Subject: [PATCH] update godoc --- server/handler/encryptData.go | 4 +- server/handler/reportDownload.go | 4 +- server/handler/snapshotAggregate.go | 13 ++--- server/handler/snapshotForceHourly.go | 6 +-- server/handler/snapshotMigrate.go | 4 +- server/handler/snapshotRegenerateHourly.go | 4 +- server/handler/snapshotRepair.go | 4 +- server/handler/snapshots.go | 4 +- server/handler/vcCleanup.go | 4 +- server/handler/vmCleanup.go | 4 +- server/handler/vmImport.go | 4 +- server/handler/vmModifyEvent.go | 6 +-- server/handler/vmMoveEvent.go | 6 +-- server/models/api_responses.go | 61 ++++++++++++++++++++++ 14 files changed, 95 insertions(+), 33 deletions(-) create mode 100644 server/models/api_responses.go diff --git a/server/handler/encryptData.go b/server/handler/encryptData.go index 80c3a43..b2ab9b1 100644 --- a/server/handler/encryptData.go +++ b/server/handler/encryptData.go @@ -14,8 +14,8 @@ import ( // @Accept json // @Produce json // @Param payload body map[string]string true "Plaintext payload" -// @Success 200 {object} map[string]string "Ciphertext response" -// @Failure 500 {object} map[string]string "Server error" +// @Success 200 {object} models.StatusMessageResponse "Ciphertext response" +// @Failure 500 {object} models.ErrorResponse "Server error" // @Router /api/encrypt [post] func (h *Handler) EncryptData(w http.ResponseWriter, r *http.Request) { //ctx := context.Background() diff --git a/server/handler/reportDownload.go b/server/handler/reportDownload.go index da689a8..1fe7eb8 100644 --- a/server/handler/reportDownload.go +++ b/server/handler/reportDownload.go @@ -14,7 +14,7 @@ import ( // @Tags reports // @Produce application/vnd.openxmlformats-officedocument.spreadsheetml.sheet // @Success 200 {file} file "Inventory XLSX report" -// @Failure 500 {object} map[string]string "Report generation failed" +// @Failure 500 {object} models.ErrorResponse "Report generation failed" // @Router /api/report/inventory [get] func (h *Handler) InventoryReportDownload(w http.ResponseWriter, r *http.Request) { @@ -48,7 +48,7 @@ func (h *Handler) InventoryReportDownload(w http.ResponseWriter, r *http.Request // @Tags reports // @Produce application/vnd.openxmlformats-officedocument.spreadsheetml.sheet // @Success 200 {file} file "Updates XLSX report" -// @Failure 500 {object} map[string]string "Report generation failed" +// @Failure 500 {object} models.ErrorResponse "Report generation failed" // @Router /api/report/updates [get] func (h *Handler) UpdateReportDownload(w http.ResponseWriter, r *http.Request) { diff --git a/server/handler/snapshotAggregate.go b/server/handler/snapshotAggregate.go index d2a83f7..c0f3c5f 100644 --- a/server/handler/snapshotAggregate.go +++ b/server/handler/snapshotAggregate.go @@ -8,6 +8,7 @@ import ( "time" "vctp/internal/settings" "vctp/internal/tasks" + "vctp/server/models" ) // SnapshotAggregateForce forces regeneration of a daily or monthly summary table. @@ -18,9 +19,9 @@ import ( // @Param type query string true "Aggregation type: daily or monthly" // @Param date query string true "Daily date (YYYY-MM-DD) or monthly date (YYYY-MM)" // @Param granularity query string false "Monthly aggregation granularity: hourly or daily" -// @Success 200 {object} map[string]string "Aggregation complete" -// @Failure 400 {object} map[string]string "Invalid request" -// @Failure 500 {object} map[string]string "Server error" +// @Success 200 {object} models.StatusResponse "Aggregation complete" +// @Failure 400 {object} models.ErrorResponse "Invalid request" +// @Failure 500 {object} models.ErrorResponse "Server error" // @Router /api/snapshots/aggregate [post] func (h *Handler) SnapshotAggregateForce(w http.ResponseWriter, r *http.Request) { snapshotType := strings.ToLower(strings.TrimSpace(r.URL.Query().Get("type"))) @@ -112,8 +113,8 @@ func (h *Handler) SnapshotAggregateForce(w http.ResponseWriter, r *http.Request) func writeJSONError(w http.ResponseWriter, status int, message string) { w.Header().Set("Content-Type", "application/json") w.WriteHeader(status) - json.NewEncoder(w).Encode(map[string]string{ - "status": "ERROR", - "message": message, + json.NewEncoder(w).Encode(models.ErrorResponse{ + Status: "ERROR", + Message: message, }) } diff --git a/server/handler/snapshotForceHourly.go b/server/handler/snapshotForceHourly.go index d9d9682..62daec4 100644 --- a/server/handler/snapshotForceHourly.go +++ b/server/handler/snapshotForceHourly.go @@ -16,9 +16,9 @@ import ( // @Accept json // @Produce json // @Param confirm query string true "Confirmation text; must be 'FORCE'" -// @Success 200 {object} map[string]string "Snapshot started" -// @Failure 400 {object} map[string]string "Invalid request" -// @Failure 500 {object} map[string]string "Server error" +// @Success 200 {object} models.StatusResponse "Snapshot started" +// @Failure 400 {object} models.ErrorResponse "Invalid request" +// @Failure 500 {object} models.ErrorResponse "Server error" // @Router /api/snapshots/hourly/force [post] func (h *Handler) SnapshotForceHourly(w http.ResponseWriter, r *http.Request) { confirm := strings.TrimSpace(r.URL.Query().Get("confirm")) diff --git a/server/handler/snapshotMigrate.go b/server/handler/snapshotMigrate.go index 36a118d..d5a514f 100644 --- a/server/handler/snapshotMigrate.go +++ b/server/handler/snapshotMigrate.go @@ -12,8 +12,8 @@ import ( // @Description Rebuilds the snapshot registry from existing tables and renames hourly tables to epoch-based names. // @Tags snapshots // @Produce json -// @Success 200 {object} map[string]interface{} "Migration results" -// @Failure 500 {object} map[string]string "Server error" +// @Success 200 {object} models.SnapshotMigrationResponse "Migration results" +// @Failure 500 {object} models.SnapshotMigrationResponse "Server error" // @Router /api/snapshots/migrate [post] func (h *Handler) SnapshotMigrate(w http.ResponseWriter, r *http.Request) { ctx := context.Background() diff --git a/server/handler/snapshotRegenerateHourly.go b/server/handler/snapshotRegenerateHourly.go index 8e62399..c6d6ecb 100644 --- a/server/handler/snapshotRegenerateHourly.go +++ b/server/handler/snapshotRegenerateHourly.go @@ -15,8 +15,8 @@ import ( // @Description Regenerates XLSX reports for hourly snapshots when the report files are missing or empty. // @Tags snapshots // @Produce json -// @Success 200 {object} map[string]interface{} "Regeneration summary" -// @Failure 500 {object} map[string]string "Server error" +// @Success 200 {object} models.SnapshotRegenerateReportsResponse "Regeneration summary" +// @Failure 500 {object} models.ErrorResponse "Server error" // @Router /api/snapshots/regenerate-hourly-reports [post] func (h *Handler) SnapshotRegenerateHourlyReports(w http.ResponseWriter, r *http.Request) { ctx := r.Context() diff --git a/server/handler/snapshotRepair.go b/server/handler/snapshotRepair.go index d6454bc..ca597ed 100644 --- a/server/handler/snapshotRepair.go +++ b/server/handler/snapshotRepair.go @@ -17,7 +17,7 @@ import ( // @Description Backfills SnapshotTime and lifecycle info for existing daily summary tables and reruns monthly lifecycle refinement using hourly data. // @Tags snapshots // @Produce json -// @Success 200 {object} map[string]string +// @Success 200 {object} models.SnapshotRepairResponse // @Router /api/snapshots/repair [post] func (h *Handler) SnapshotRepair(w http.ResponseWriter, r *http.Request) { if r.Method != http.MethodPost { @@ -102,7 +102,7 @@ func (h *Handler) repairDailySummaries(ctx context.Context, now time.Time) (repa // @Description Rebuilds snapshot registry, backfills per-vCenter totals, repairs daily summaries (SnapshotTime/lifecycle), and refines monthly lifecycle. // @Tags snapshots // @Produce json -// @Success 200 {object} map[string]string +// @Success 200 {object} models.SnapshotRepairSuiteResponse // @Router /api/snapshots/repair/all [post] func (h *Handler) SnapshotRepairSuite(w http.ResponseWriter, r *http.Request) { if r.Method != http.MethodPost { diff --git a/server/handler/snapshots.go b/server/handler/snapshots.go index a50eec6..8627e94 100644 --- a/server/handler/snapshots.go +++ b/server/handler/snapshots.go @@ -55,8 +55,8 @@ func (h *Handler) SnapshotMonthlyList(w http.ResponseWriter, r *http.Request) { // @Produce application/vnd.openxmlformats-officedocument.spreadsheetml.sheet // @Param table query string true "Snapshot table name" // @Success 200 {file} file "Snapshot XLSX report" -// @Failure 400 {object} map[string]string "Invalid request" -// @Failure 500 {object} map[string]string "Server error" +// @Failure 400 {object} models.ErrorResponse "Invalid request" +// @Failure 500 {object} models.ErrorResponse "Server error" // @Router /api/report/snapshot [get] func (h *Handler) SnapshotReportDownload(w http.ResponseWriter, r *http.Request) { ctx := context.Background() diff --git a/server/handler/vcCleanup.go b/server/handler/vcCleanup.go index 867d94b..de43642 100644 --- a/server/handler/vcCleanup.go +++ b/server/handler/vcCleanup.go @@ -16,8 +16,8 @@ import ( // @Deprecated // @Produce json // @Param vc_url query string true "vCenter URL" -// @Success 200 {object} map[string]string "Cleanup completed" -// @Failure 400 {object} map[string]string "Invalid request" +// @Success 200 {object} models.StatusMessageResponse "Cleanup completed" +// @Failure 400 {object} models.ErrorResponse "Invalid request" // @Router /api/cleanup/vcenter [delete] func (h *Handler) VcCleanup(w http.ResponseWriter, r *http.Request) { ctx := context.Background() diff --git a/server/handler/vmCleanup.go b/server/handler/vmCleanup.go index 1be2bea..c5d6ecc 100644 --- a/server/handler/vmCleanup.go +++ b/server/handler/vmCleanup.go @@ -17,8 +17,8 @@ import ( // @Produce json // @Param vm_id query string true "VM ID" // @Param datacenter_name query string true "Datacenter name" -// @Success 200 {object} map[string]string "Cleanup completed" -// @Failure 400 {object} map[string]string "Invalid request" +// @Success 200 {object} models.StatusMessageResponse "Cleanup completed" +// @Failure 400 {object} models.ErrorResponse "Invalid request" // @Router /api/inventory/vm/delete [delete] func (h *Handler) VmCleanup(w http.ResponseWriter, r *http.Request) { ctx := context.Background() diff --git a/server/handler/vmImport.go b/server/handler/vmImport.go index bcabefd..b454add 100644 --- a/server/handler/vmImport.go +++ b/server/handler/vmImport.go @@ -21,8 +21,8 @@ import ( // @Accept json // @Produce json // @Param import body models.ImportReceived true "Bulk import payload" -// @Success 200 {object} map[string]string "Import processed" -// @Failure 500 {object} map[string]string "Server error" +// @Success 200 {object} models.StatusMessageResponse "Import processed" +// @Failure 500 {object} models.ErrorResponse "Server error" // @Router /api/import/vm [post] func (h *Handler) VmImport(w http.ResponseWriter, r *http.Request) { // Read request body diff --git a/server/handler/vmModifyEvent.go b/server/handler/vmModifyEvent.go index 966d4a5..91fd76e 100644 --- a/server/handler/vmModifyEvent.go +++ b/server/handler/vmModifyEvent.go @@ -27,9 +27,9 @@ import ( // @Accept json // @Produce json // @Param event body models.CloudEventReceived true "CloudEvent payload" -// @Success 200 {object} map[string]string "Modify event processed" -// @Success 202 {object} map[string]string "No relevant changes" -// @Failure 500 {object} map[string]string "Server error" +// @Success 200 {object} models.StatusMessageResponse "Modify event processed" +// @Success 202 {object} models.StatusMessageResponse "No relevant changes" +// @Failure 500 {object} models.ErrorResponse "Server error" // @Router /api/event/vm/modify [post] func (h *Handler) VmModifyEvent(w http.ResponseWriter, r *http.Request) { var configChanges []map[string]string diff --git a/server/handler/vmMoveEvent.go b/server/handler/vmMoveEvent.go index be3dc63..626b8a2 100644 --- a/server/handler/vmMoveEvent.go +++ b/server/handler/vmMoveEvent.go @@ -22,9 +22,9 @@ import ( // @Accept json // @Produce json // @Param event body models.CloudEventReceived true "CloudEvent payload" -// @Success 200 {object} map[string]string "Move event processed" -// @Failure 400 {object} map[string]string "Invalid request" -// @Failure 500 {object} map[string]string "Server error" +// @Success 200 {object} models.StatusMessageResponse "Move event processed" +// @Failure 400 {object} models.ErrorResponse "Invalid request" +// @Failure 500 {object} models.ErrorResponse "Server error" // @Router /api/event/vm/move [post] func (h *Handler) VmMoveEvent(w http.ResponseWriter, r *http.Request) { params := queries.CreateUpdateParams{} diff --git a/server/models/api_responses.go b/server/models/api_responses.go new file mode 100644 index 0000000..7c7174c --- /dev/null +++ b/server/models/api_responses.go @@ -0,0 +1,61 @@ +package models + +// StatusResponse represents a simple status-only JSON response. +type StatusResponse struct { + Status string `json:"status"` +} + +// StatusMessageResponse represents a status + message JSON response. +type StatusMessageResponse struct { + Status string `json:"status"` + Message string `json:"message"` +} + +// ErrorResponse represents a standard error JSON response. +type ErrorResponse struct { + Status string `json:"status"` + Message string `json:"message"` +} + +// SnapshotMigrationStats mirrors the snapshot registry migration stats payload. +type SnapshotMigrationStats struct { + HourlyRenamed int `json:"HourlyRenamed"` + HourlyRegistered int `json:"HourlyRegistered"` + DailyRegistered int `json:"DailyRegistered"` + MonthlyRegistered int `json:"MonthlyRegistered"` + Errors int `json:"Errors"` +} + +// SnapshotMigrationResponse captures snapshot registry migration results. +type SnapshotMigrationResponse struct { + Status string `json:"status"` + Error string `json:"error,omitempty"` + Stats SnapshotMigrationStats `json:"stats"` +} + +// SnapshotRegenerateReportsResponse describes the hourly report regeneration response. +type SnapshotRegenerateReportsResponse struct { + Status string `json:"status"` + Total int `json:"total"` + Regenerated int `json:"regenerated"` + Skipped int `json:"skipped"` + Errors int `json:"errors"` + ReportsDir string `json:"reports_dir"` + SnapshotType string `json:"snapshotType"` +} + +// SnapshotRepairResponse describes the daily snapshot repair response. +type SnapshotRepairResponse struct { + Status string `json:"status"` + Repaired string `json:"repaired"` + Failed string `json:"failed"` +} + +// SnapshotRepairSuiteResponse describes the full repair suite response. +type SnapshotRepairSuiteResponse struct { + Status string `json:"status"` + DailyRepaired string `json:"daily_repaired"` + DailyFailed string `json:"daily_failed"` + MonthlyRefined string `json:"monthly_refined"` + MonthlyFailed string `json:"monthly_failed"` +}