Chore: Move swagger definitions to the handlers (#52643)

2022-07-27 09:54:37 -04:00
parent c968b76279
commit 7ba076de10
76 changed files with 6022 additions and 6161 deletions
@@ -39,6 +39,15 @@ func (hs *HTTPServer) ValidateOrgAlert(c *models.ReqContext) {
 	}
 }

+// swagger:route GET /alerts/states-for-dashboard legacy_alerts getDashboardStates
+//
+// Get alert states for a dashboard.
+//
+// Responses:
+// Responses:
+// 200: getDashboardStatesResponse
+// 400: badRequestError
+// 500: internalServerError
 func (hs *HTTPServer) GetAlertStatesForDashboard(c *models.ReqContext) response.Response {
 	dashboardID := c.QueryInt64("dashboardId")

@@ -58,7 +67,14 @@ func (hs *HTTPServer) GetAlertStatesForDashboard(c *models.ReqContext) response.
 	return response.JSON(http.StatusOK, query.Result)
 }

-// GET /api/alerts
+// swagger:route GET /alerts legacy_alerts getAlerts
+//
+// Get legacy alerts.
+//
+// Responses:
+// 200: getAlertsResponse
+// 401: unauthorisedError
+// 500: internalServerError
 func (hs *HTTPServer) GetAlerts(c *models.ReqContext) response.Response {
 	dashboardQuery := c.Query("dashboardQuery")
 	dashboardTags := c.QueryStrings("dashboardTag")
@@ -136,7 +152,16 @@ func (hs *HTTPServer) GetAlerts(c *models.ReqContext) response.Response {
 	return response.JSON(http.StatusOK, query.Result)
 }

-// POST /api/alerts/test
+// swagger:route POST /alerts/test legacy_alerts testAlert
+//
+// Test alert.
+//
+// Responses:
+// 200: testAlertResponse
+// 400: badRequestError
+// 422: unprocessableEntityError
+// 403: forbiddenError
+// 500: internalServerError
 func (hs *HTTPServer) AlertTest(c *models.ReqContext) response.Response {
 	dto := dtos.AlertTestCommand{}
 	if err := web.Bind(c.Req, &dto); err != nil {
@@ -180,7 +205,17 @@ func (hs *HTTPServer) AlertTest(c *models.ReqContext) response.Response {
 	return response.JSON(http.StatusOK, dtoRes)
 }

-// GET /api/alerts/:id
+// swagger:route GET /alerts/{alert_id} legacy_alerts getAlertByID
+//
+// Get alert by ID.
+//
+// “evalMatches” data in the response is cached in the db when and only when the state of the alert changes (e.g. transitioning from “ok” to “alerting” state).
+// If data from one server triggers the alert first and, before that server is seen leaving alerting state, a second server also enters a state that would trigger the alert, the second server will not be visible in “evalMatches” data.
+//
+// Responses:
+// 200: getAlertResponse
+// 401: unauthorisedError
+// 500: internalServerError
 func (hs *HTTPServer) GetAlert(c *models.ReqContext) response.Response {
 	id, err := strconv.ParseInt(web.Params(c.Req)[":alertId"], 10, 64)
 	if err != nil {
@@ -206,6 +241,17 @@ func (hs *HTTPServer) GetAlertNotifiers(ngalertEnabled bool) func(*models.ReqCon
 	}
 }

+// swagger:route GET /alert-notifications/lookup legacy_alerts_notification_channels getAlertNotificationLookup
+//
+// Get all notification channels (lookup)
+//
+// Returns all notification channels, but with less detailed information. Accessible by any authenticated user and is mainly used by providing alert notification channels in Grafana UI when configuring alert rule.
+//
+// Responses:
+// 200: getAlertNotificationLookupResponse
+// 401: unauthorisedError
+// 403: forbiddenError
+// 500: internalServerError
 func (hs *HTTPServer) GetAlertNotificationLookup(c *models.ReqContext) response.Response {
 	alertNotifications, err := hs.getAlertNotificationsInternal(c)
 	if err != nil {
@@ -221,6 +267,17 @@ func (hs *HTTPServer) GetAlertNotificationLookup(c *models.ReqContext) response.
 	return response.JSON(http.StatusOK, result)
 }

+// swagger:route GET /alert-notifications legacy_alerts_notification_channels getAlertNotificationChannels
+//
+// Get all notification channels.
+//
+// Returns all notification channels that the authenticated user has permission to view.
+//
+// Responses:
+// 200: getAlertNotificationChannelsResponse
+// 401: unauthorisedError
+// 403: forbiddenError
+// 500: internalServerError
 func (hs *HTTPServer) GetAlertNotifications(c *models.ReqContext) response.Response {
 	alertNotifications, err := hs.getAlertNotificationsInternal(c)
 	if err != nil {
@@ -246,6 +303,18 @@ func (hs *HTTPServer) getAlertNotificationsInternal(c *models.ReqContext) ([]*mo
 	return query.Result, nil
 }

+// swagger:route GET /alert-notifications/{notification_channel_id} legacy_alerts_notification_channels getAlertNotificationChannelByID
+//
+// Get notification channel by ID.
+//
+// Returns the notification channel given the notification channel ID.
+//
+// Responses:
+// 200: getAlertNotificationChannelResponse
+// 401: unauthorisedError
+// 403: forbiddenError
+// 404: notFoundError
+// 500: internalServerError
 func (hs *HTTPServer) GetAlertNotificationByID(c *models.ReqContext) response.Response {
 	notificationId, err := strconv.ParseInt(web.Params(c.Req)[":notificationId"], 10, 64)
 	if err != nil {
@@ -271,6 +340,18 @@ func (hs *HTTPServer) GetAlertNotificationByID(c *models.ReqContext) response.Re
 	return response.JSON(http.StatusOK, dtos.NewAlertNotification(query.Result))
 }

+// swagger:route GET /alert-notifications/uid/{notification_channel_uid} legacy_alerts_notification_channels getAlertNotificationChannelByUID
+//
+// Get notification channel by UID
+//
+// Returns the notification channel given the notification channel UID.
+//
+// Responses:
+// 200: getAlertNotificationChannelResponse
+// 401: unauthorisedError
+// 403: forbiddenError
+// 404: notFoundError
+// 500: internalServerError
 func (hs *HTTPServer) GetAlertNotificationByUID(c *models.ReqContext) response.Response {
 	query := &models.GetAlertNotificationsWithUidQuery{
 		OrgId: c.OrgId,
@@ -292,6 +373,18 @@ func (hs *HTTPServer) GetAlertNotificationByUID(c *models.ReqContext) response.R
 	return response.JSON(http.StatusOK, dtos.NewAlertNotification(query.Result))
 }

+// swagger:route POST /alert-notifications legacy_alerts_notification_channels createAlertNotificationChannel
+//
+// Create notification channel.
+//
+// You can find the full list of [supported notifiers](https://grafana.com/docs/grafana/latest/alerting/old-alerting/notifications/#list-of-supported-notifiers) on the alert notifiers page.
+//
+// Responses:
+// 200: getAlertNotificationChannelResponse
+// 401: unauthorisedError
+// 403: forbiddenError
+// 409: conflictError
+// 500: internalServerError
 func (hs *HTTPServer) CreateAlertNotification(c *models.ReqContext) response.Response {
 	cmd := models.CreateAlertNotificationCommand{}
 	if err := web.Bind(c.Req, &cmd); err != nil {
@@ -313,6 +406,18 @@ func (hs *HTTPServer) CreateAlertNotification(c *models.ReqContext) response.Res
 	return response.JSON(http.StatusOK, dtos.NewAlertNotification(cmd.Result))
 }

+// swagger:route PUT /alert-notifications/{notification_channel_id} legacy_alerts_notification_channels updateAlertNotificationChannel
+//
+// Update notification channel by ID.
+//
+// Updates an existing notification channel identified by ID.
+//
+// Responses:
+// 200: getAlertNotificationChannelResponse
+// 401: unauthorisedError
+// 403: forbiddenError
+// 404: notFoundError
+// 500: internalServerError
 func (hs *HTTPServer) UpdateAlertNotification(c *models.ReqContext) response.Response {
 	cmd := models.UpdateAlertNotificationCommand{}
 	if err := web.Bind(c.Req, &cmd); err != nil {
@@ -348,6 +453,18 @@ func (hs *HTTPServer) UpdateAlertNotification(c *models.ReqContext) response.Res
 	return response.JSON(http.StatusOK, dtos.NewAlertNotification(query.Result))
 }

+// swagger:route PUT /alert-notifications/uid/{notification_channel_uid} legacy_alerts_notification_channels updateAlertNotificationChannelByUID
+//
+// Update notification channel by UID.
+//
+// Updates an existing notification channel identified by uid.
+//
+// Responses:
+// 200: getAlertNotificationChannelResponse
+// 401: unauthorisedError
+// 403: forbiddenError
+// 404: notFoundError
+// 500: internalServerError
 func (hs *HTTPServer) UpdateAlertNotificationByUID(c *models.ReqContext) response.Response {
 	cmd := models.UpdateAlertNotificationWithUidCommand{}
 	if err := web.Bind(c.Req, &cmd); err != nil {
@@ -436,6 +553,18 @@ func (hs *HTTPServer) fillWithSecureSettingsDataByUID(ctx context.Context, cmd *
 	return nil
 }

+// swagger:route DELETE /alert-notifications/{notification_channel_id} legacy_alerts_notification_channels deleteAlertNotificationChannel
+//
+// Delete alert notification by ID.
+//
+// Deletes an existing notification channel identified by ID.
+//
+// Responses:
+// 200: okResponse
+// 401: unauthorisedError
+// 403: forbiddenError
+// 404: notFoundError
+// 500: internalServerError
 func (hs *HTTPServer) DeleteAlertNotification(c *models.ReqContext) response.Response {
 	notificationId, err := strconv.ParseInt(web.Params(c.Req)[":notificationId"], 10, 64)
 	if err != nil {
@@ -457,6 +586,18 @@ func (hs *HTTPServer) DeleteAlertNotification(c *models.ReqContext) response.Res
 	return response.Success("Notification deleted")
 }

+// swagger:route DELETE /alert-notifications/uid/{notification_channel_uid} legacy_alerts_notification_channels deleteAlertNotificationChannelByUID
+//
+// Delete alert notification by UID.
+//
+// Deletes an existing notification channel identified by UID.
+//
+// Responses:
+// 200: deleteAlertNotificationChannelResponse
+// 401: unauthorisedError
+// 403: forbiddenError
+// 404: notFoundError
+// 500: internalServerError
 func (hs *HTTPServer) DeleteAlertNotificationByUID(c *models.ReqContext) response.Response {
 	cmd := models.DeleteAlertNotificationWithUidCommand{
 		OrgId: c.OrgId,
@@ -476,7 +617,19 @@ func (hs *HTTPServer) DeleteAlertNotificationByUID(c *models.ReqContext) respons
 	})
 }

-// POST /api/alert-notifications/test
+// swagger:route POST /alert-notifications/test legacy_alerts_notification_channels notificationChannelTest
+//
+// Test notification channel.
+//
+// Sends a test notification to the channel.
+//
+// Responses:
+// 200: okResponse
+// 400: badRequestError
+// 401: unauthorisedError
+// 403: forbiddenError
+// 412: SMTPNotEnabledError
+// 500: internalServerError
 func (hs *HTTPServer) NotificationTest(c *models.ReqContext) response.Response {
 	dto := dtos.NotificationTestCommand{}
 	if err := web.Bind(c.Req, &dto); err != nil {
@@ -506,7 +659,16 @@ func (hs *HTTPServer) NotificationTest(c *models.ReqContext) response.Response {
 	return response.Success("Test notification sent")
 }

-// POST /api/alerts/:alertId/pause
+// swagger:route POST /alerts/{alert_id}/pause legacy_alerts pauseAlert
+//
+// Pause/unpause alert by id.
+//
+// Responses:
+// 200: pauseAlertResponse
+// 401: unauthorisedError
+// 403: forbiddenError
+// 404: notFoundError
+// 500: internalServerError
 func (hs *HTTPServer) PauseAlert(legacyAlertingEnabled *bool) func(c *models.ReqContext) response.Response {
 	if legacyAlertingEnabled == nil || !*legacyAlertingEnabled {
 		return func(_ *models.ReqContext) response.Response {
@@ -574,7 +736,18 @@ func (hs *HTTPServer) PauseAlert(legacyAlertingEnabled *bool) func(c *models.Req
 	}
 }

-// POST /api/admin/pause-all-alerts
+// swagger:route POST /admin/pause-all-alerts admin pauseAllAlerts
+//
+// Pause/unpause all (legacy) alerts.
+//
+// Security:
+// - basic:
+//
+// Responses:
+// 200: pauseAlertsResponse
+// 401: unauthorisedError
+// 403: forbiddenError
+// 500: internalServerError
 func (hs *HTTPServer) PauseAllAlerts(legacyAlertingEnabled *bool) func(c *models.ReqContext) response.Response {
 	if legacyAlertingEnabled == nil || !*legacyAlertingEnabled {
 		return func(_ *models.ReqContext) response.Response {
@@ -611,3 +784,248 @@ func (hs *HTTPServer) PauseAllAlerts(legacyAlertingEnabled *bool) func(c *models
 		return response.JSON(http.StatusOK, result)
 	}
 }
+
+// swagger:parameters pauseAllAlerts
+type PauseAllAlertsParams struct {
+	// in:body
+	// required:true
+	Body dtos.PauseAllAlertsCommand `json:"body"`
+}
+
+// swagger:parameters deleteAlertNotificationChannel
+type DeleteAlertNotificationChannelParams struct {
+	// in:path
+	// required:true
+	NotificationID int64 `json:"notification_channel_id"`
+}
+
+// swagger:parameters getAlertNotificationChannelByID
+type GetAlertNotificationChannelByIDParams struct {
+	// in:path
+	// required:true
+	NotificationID int64 `json:"notification_channel_id"`
+}
+
+// swagger:parameters deleteAlertNotificationChannelByUID
+type DeleteAlertNotificationChannelByUIDParams struct {
+	// in:path
+	// required:true
+	NotificationUID string `json:"notification_channel_uid"`
+}
+
+// swagger:parameters getAlertNotificationChannelByUID
+type GetAlertNotificationChannelByUIDParams struct {
+	// in:path
+	// required:true
+	NotificationUID string `json:"notification_channel_uid"`
+}
+
+// swagger:parameters notificationChannelTest
+type NotificationChannelTestParams struct {
+	// in:body
+	// required:true
+	Body dtos.NotificationTestCommand `json:"body"`
+}
+
+// swagger:parameters createAlertNotificationChannel
+type CreateAlertNotificationChannelParams struct {
+	// in:body
+	// required:true
+	Body models.CreateAlertNotificationCommand `json:"body"`
+}
+
+// swagger:parameters updateAlertNotificationChannel
+type UpdateAlertNotificationChannelParams struct {
+	// in:body
+	// required:true
+	Body models.UpdateAlertNotificationCommand `json:"body"`
+	// in:path
+	// required:true
+	NotificationID int64 `json:"notification_channel_id"`
+}
+
+// swagger:parameters updateAlertNotificationChannelByUID
+type UpdateAlertNotificationChannelByUIDParams struct {
+	// in:body
+	// required:true
+	Body models.UpdateAlertNotificationWithUidCommand `json:"body"`
+	// in:path
+	// required:true
+	NotificationUID string `json:"notification_channel_uid"`
+}
+
+// swagger:parameters getAlertByID
+type GetAlertByIDParams struct {
+	// in:path
+	// required:true
+	AlertID string `json:"alert_id"`
+}
+
+// swagger:parameters pauseAlert
+type PauseAlertParams struct {
+	// in:path
+	// required:true
+	AlertID string `json:"alert_id"`
+	// in:body
+	// required:true
+	Body dtos.PauseAlertCommand `json:"body"`
+}
+
+// swagger:parameters getAlerts
+type GetAlertsParams struct {
+	// Limit response to alerts in specified dashboard(s). You can specify multiple dashboards.
+	// in:query
+	// required:false
+	DashboardID []string `json:"dashboardId"`
+	//  Limit response to alert for a specified panel on a dashboard.
+	// in:query
+	// required:false
+	PanelID int64 `json:"panelId"`
+	// Limit response to alerts having a name like this value.
+	// in:query
+	// required: false
+	Query string `json:"query"`
+	// Return alerts with one or more of the following alert states
+	// in:query
+	// required:false
+	// Description:
+	// * `all`
+	// * `no_data`
+	// * `paused`
+	// * `alerting`
+	// * `ok`
+	// * `pending`
+	// * `unknown`
+	// enum: all,no_data,paused,alerting,ok,pending,unknown
+	State string `json:"state"`
+	// Limit response to X number of alerts.
+	// in:query
+	// required:false
+	Limit int64 `json:"limit"`
+	// Limit response to alerts of dashboards in specified folder(s). You can specify multiple folders
+	// in:query
+	// required:false
+	// type array
+	// collectionFormat: multi
+	FolderID []string `json:"folderId"`
+	// Limit response to alerts having a dashboard name like this value./ Limit response to alerts having a dashboard name like this value.
+	// in:query
+	// required:false
+	DashboardQuery string `json:"dashboardQuery"`
+	// Limit response to alerts of dashboards with specified tags. To do an “AND” filtering with multiple tags, specify the tags parameter multiple times
+	// in:query
+	// required:false
+	// type: array
+	// collectionFormat: multi
+	DashboardTag []string `json:"dashboardTag"`
+}
+
+// swagger:parameters testAlert
+type TestAlertParams struct {
+	// in:body
+	Body dtos.AlertTestCommand `json:"body"`
+}
+
+// swagger:parameters getDashboardStates
+type GetDashboardStatesParams struct {
+	// in:query
+	// required: true
+	DashboardID int64 `json:"dashboardId"`
+}
+
+// swagger:response pauseAlertsResponse
+type PauseAllAlertsResponse struct {
+	// in:body
+	Body struct {
+		// AlertsAffected is the number of the affected alerts.
+		// required: true
+		AlertsAffected int64 `json:"alertsAffected"`
+		// required: true
+		Message string `json:"message"`
+		// Alert result state
+		// required true
+		State string `json:"state"`
+	} `json:"body"`
+}
+
+// swagger:response getAlertNotificationChannelsResponse
+type GetAlertNotificationChannelsResponse struct {
+	// The response message
+	// in: body
+	Body []*dtos.AlertNotification `json:"body"`
+}
+
+// swagger:response getAlertNotificationLookupResponse
+type LookupAlertNotificationChannelsResponse struct {
+	// The response message
+	// in: body
+	Body []*dtos.AlertNotificationLookup `json:"body"`
+}
+
+// swagger:response getAlertNotificationChannelResponse
+type GetAlertNotificationChannelResponse struct {
+	// The response message
+	// in: body
+	Body *dtos.AlertNotification `json:"body"`
+}
+
+// swagger:response deleteAlertNotificationChannelResponse
+type DeleteAlertNotificationChannelResponse struct {
+	// The response message
+	// in: body
+	Body struct {
+		// ID Identifier of the deleted notification channel.
+		// required: true
+		// example: 65
+		ID int64 `json:"id"`
+
+		// Message Message of the deleted notificatiton channel.
+		// required: true
+		Message string `json:"message"`
+	} `json:"body"`
+}
+
+// swagger:response SMTPNotEnabledError
+type SMTPNotEnabledError PreconditionFailedError
+
+// swagger:response getAlertsResponse
+type GetAlertsResponse struct {
+	// The response message
+	// in: body
+	Body []*models.AlertListItemDTO `json:"body"`
+}
+
+// swagger:response getAlertResponse
+type GetAlertResponse struct {
+	// The response message
+	// in: body
+	Body *models.Alert `json:"body"`
+}
+
+// swagger:response pauseAlertResponse
+type PauseAlertResponse struct {
+	// in:body
+	Body struct {
+		// required: true
+		AlertID int64 `json:"alertId"`
+		// required: true
+		Message string `json:"message"`
+		// Alert result state
+		// required true
+		State string `json:"state"`
+	} `json:"body"`
+}
+
+// swagger:response testAlertResponse
+type TestAlertResponse struct {
+	// The response message
+	// in: body
+	Body *dtos.AlertTestResult `json:"body"`
+}
+
+// swagger:response getDashboardStatesResponse
+type GetDashboardStatesResponse struct {
+	// The response message
+	// in: body
+	Body []*models.AlertStateInfoDTO `json:"body"`
+}