Alerting: improve provisioning docs (#50347)

* Alerting: improve provisioning docs

* add new provisioning page

* add api docs

* fix formatting and add better descriptions

* fix typo

pkg/services/ngalert/api/tooling/definitions/provisioning_alert_rules.go

@@ -54,21 +54,43 @@ type AlertRulePayload struct {
 }
 
 type AlertRule struct {
-	ID           int64                      `json:"id"`
-	UID          string                     `json:"uid"`
-	OrgID        int64                      `json:"orgID"`
-	FolderUID    string                     `json:"folderUID"`
-	RuleGroup    string                     `json:"ruleGroup"`
-	Title        string                     `json:"title"`
-	Condition    string                     `json:"condition"`
-	Data         []models.AlertQuery        `json:"data"`
-	Updated      time.Time                  `json:"updated,omitempty"`
-	NoDataState  models.NoDataState         `json:"noDataState"`
+	ID  int64  `json:"id"`
+	UID string `json:"uid"`
+	// required: true
+	OrgID int64 `json:"orgID"`
+	// required: true
+	// example: project_x
+	FolderUID string `json:"folderUID"`
+	// required: true
+	// minLength: 1
+	// maxLength: 190
+	// example: eval_group_1
+	RuleGroup string `json:"ruleGroup"`
+	// required: true
+	// minLength: 1
+	// maxLength: 190
+	// example: Always firing
+	Title string `json:"title"`
+	// required: true
+	// example: A
+	Condition string `json:"condition"`
+	// required: true
+	// example: [{"refId":"A","queryType":"","relativeTimeRange":{"from":0,"to":0},"datasourceUid":"-100","model":{"conditions":[{"evaluator":{"params":[0,0],"type":"gt"},"operator":{"type":"and"},"query":{"params":[]},"reducer":{"params":[],"type":"avg"},"type":"query"}],"datasource":{"type":"__expr__","uid":"__expr__"},"expression":"1 == 1","hide":false,"intervalMs":1000,"maxDataPoints":43200,"refId":"A","type":"math"}}]
+	Data []models.AlertQuery `json:"data"`
+	// readonly: true
+	Updated time.Time `json:"updated,omitempty"`
+	// required: true
+	NoDataState models.NoDataState `json:"noDataState"`
+	// required: true
 	ExecErrState models.ExecutionErrorState `json:"execErrState"`
-	For          time.Duration              `json:"for"`
-	Annotations  map[string]string          `json:"annotations,omitempty"`
-	Labels       map[string]string          `json:"labels,omitempty"`
-	Provenance   models.Provenance          `json:"provenance,omitempty"`
+	// required: true
+	For time.Duration `json:"for"`
+	// example: {"runbook_url": "https://supercoolrunbook.com/page/13"}
+	Annotations map[string]string `json:"annotations,omitempty"`
+	// example: {"team": "sre-team-1"}
+	Labels map[string]string `json:"labels,omitempty"`
+	// readonly: true
+	Provenance models.Provenance `json:"provenance,omitempty"`
 }
 
 func (a *AlertRule) UpstreamModel() models.AlertRule {

pkg/services/ngalert/api/tooling/definitions/provisioning_contactpoints.go

@@ -50,7 +50,7 @@ import (
 
 // swagger:parameters RoutePutContactpoint RouteDeleteContactpoints
 type ContactPointUIDReference struct {
-	// ContactPointUID should be the contact point UID identifier
+	// UID should be the contact point unique identifier
 	// in:path
 	UID string
 }
@@ -64,16 +64,24 @@ type ContactPointPayload struct {
 // EmbeddedContactPoint is the contact point type that is used
 // by grafanas embedded alertmanager implementation.
 type EmbeddedContactPoint struct {
-	// UID is the unique identifier of the contact point. This will be
-	// automatically set be the Grafana.
+	// UID is the unique identifier of the contact point. The UID can be
+	// set by the user.
+	// example: my_external_reference
 	UID string `json:"uid"`
 	// Name is used as grouping key in the UI. Contact points with the
 	// same name will be grouped in the UI.
-	Name                  string           `json:"name" binding:"required"`
-	Type                  string           `json:"type" binding:"required"`
-	Settings              *simplejson.Json `json:"settings" binding:"required"`
-	DisableResolveMessage bool             `json:"disableResolveMessage"`
-	Provenance            string           `json:"provenance"`
+	// example: webhook_1
+	Name string `json:"name" binding:"required"`
+	// required: true
+	// example: webhook
+	// enum: alertmanager, dingding, discord, email, googlechat, kafka, line, opsgenie, pagerduty, pushover, sensugo, slack, teams, telegram, threema, victorops, webhook, wecom
+	Type string `json:"type" binding:"required"`
+	// required: true
+	Settings *simplejson.Json `json:"settings" binding:"required"`
+	// example: false
+	DisableResolveMessage bool `json:"disableResolveMessage"`
+	// readonly: true
+	Provenance string `json:"provenance,omitempty"`
 }
 
 const RedactedValue = "[REDACTED]"