Alerting: Add support for documenting which alerting APIs are stable (#49018)

* Support for documenting stable vs unstable alerting routes

* empty commit, restart drone

* Touch-up references in root makefile and drop trailing escape newline

* Rebase and regenerate

* Extend README with docs for this change

Makefile

@@ -35,7 +35,7 @@ node_modules: package.json yarn.lock ## Install node modules.
 ##@ Swagger
 SPEC_TARGET = public/api-spec.json
 MERGED_SPEC_TARGET := public/api-merged.json
-NGALERT_SPEC_TARGET = pkg/services/ngalert/api/tooling/post.json
+NGALERT_SPEC_TARGET = pkg/services/ngalert/api/tooling/api.json
 
 $(SPEC_TARGET): $(API_DEFINITION_FILES) ## Generate API spec
 	docker run --rm -it \
@@ -53,10 +53,10 @@ $(SPEC_TARGET): $(API_DEFINITION_FILES) ## Generate API spec
 swagger-api-spec: gen-go $(SPEC_TARGET) $(MERGED_SPEC_TARGET)
 
 $(NGALERT_SPEC_TARGET):
-	+$(MAKE) -C pkg/services/ngalert/api/tooling post.json
+	+$(MAKE) -C pkg/services/ngalert/api/tooling api.json
 
 $(MERGED_SPEC_TARGET): $(SPEC_TARGET) $(NGALERT_SPEC_TARGET) ## Merge generated and ngalert API specs
-	go run pkg/api/docs/merge/merge_specs.go -o=public/api-merged.json $(<) pkg/services/ngalert/api/tooling/post.json
+	go run pkg/api/docs/merge/merge_specs.go -o=public/api-merged.json $(<) pkg/services/ngalert/api/tooling/api.json
 
 ensure_go-swagger_mac:
 	@hash swagger &>/dev/null || (brew tap go-swagger/go-swagger && brew install go-swagger)

pkg/services/ngalert/api/tooling/.gitignore

@@ -1 +1,2 @@
-go/
+go/
+spec-stable.json

pkg/services/ngalert/api/tooling/Makefile

@@ -11,24 +11,29 @@ PATH_UP = ../../../../..
 
 GENERATED_GO_MATCHERS = ./go/*.go
 
-spec.json: $(GO_PKG_FILES)
+spec.json spec-stable.json: $(GO_PKG_FILES)
 	# this is slow because this image does not use the cache
 	# https://github.com/go-swagger/go-swagger/blob/v0.27.0/Dockerfile#L5
 	docker run --rm -it \
 		-w /src/$(PATH_DOWN) \
 		-v $$(pwd)/$(PATH_UP):/src \
+		--entrypoint sh \
 		quay.io/goswagger/swagger:$(SWAGGER_TAG) \
-		generate spec -m -o $@
+		-c \
+		"swagger generate spec -m -o $@; swagger generate spec -m --include-tag=stable -o spec-stable.json"
 
 ensure_go-swagger_mac:
 	@hash swagger &>/dev/null || (brew tap go-swagger/go-swagger && brew install go-swagger)
 
 spec.json-mac: ensure_go-swagger_mac $(GO_PKG_FILES)
-	swagger generate spec -m -w $(API_DIR) -o spec.json
+	swagger generate spec -m -w $(API_DIR) -o spec.json && swagger generate spec -m --include-tag=stable -o ngalert.json
 
 post.json: spec.json
 	go run cmd/clean-swagger/main.go -if $(<) -of $@
 
+api.json: spec-stable.json
+	go run cmd/clean-swagger/main.go -if $(<) -of $@
+
 swagger-codegen-api:
 	docker run --rm -v $$(pwd):/local --user $$(id -u):$$(id -g) swaggerapi/swagger-codegen-cli generate \
 	-i /local/post.json \
@@ -55,4 +60,7 @@ clean:
 serve: post.json
 	docker run --rm -p 80:8080 -v $$(pwd):/tmp -e SWAGGER_FILE=/tmp/$(<) swaggerapi/swagger-editor
 
-all: post.json swagger-codegen-api fix copy-files clean	
+serve-stable: api.json
+	docker run --rm -p 80:8080 -v $$(pwd):/tmp -e SWAGGER_FILE=/tmp/$(<) swaggerapi/swagger-editor
+
+all: post.json api.json swagger-codegen-api fix copy-files clean

pkg/services/ngalert/api/tooling/README.md

@@ -16,3 +16,13 @@ This aims to define the unified alerting API as code. It generates OpenAPI defin
 The current state of Swagger extraction from golang is relatively limited. It's easier to generate server stubs from an existing Swagger doc, as there are limitations with producing a Swagger doc from a hand-written API stub. The current extractor instead relies on comments describing the routes, but the comments and actual implementation may drift, which we don't want to allow.
 
 Instead, we use a hybrid approach - we define the types in Golang, with comments describing the routes, in a standalone package with minimal dependencies. From this, we produce a Swagger doc, and then turn the Swagger doc back into a full-blown server stub.
+
+### Stability
+
+We have some endpoints that we document publically as being stable, and others that we consider unstable. The stable endpoints are documented in `api.json`, where all endpoints are available in `post.json`.
+
+To stabilize an endpoint, add the `stable` tag to its route comment:
+
+```
+// swagger:route GET /api/provisioning/contact-points provisioning stable RouteGetContactpoints
+```

pkg/services/ngalert/api/tooling/cmd/clean-swagger/main.go

@@ -63,6 +63,39 @@ func main() {
 		}
 	}
 
+	paths, ok := data["paths"].(map[string]interface{})
+	if !ok {
+		log.Fatal("no paths")
+	}
+
+	for _, path := range paths {
+		path, ok := path.(map[string]interface{})
+		if !ok {
+			log.Fatal("invalid path")
+		}
+
+		for _, op := range path {
+			op, ok := op.(map[string]interface{})
+			if !ok {
+				continue
+			}
+
+			tags, ok := op["tags"].([]interface{})
+			if !ok {
+				log.Println("invalid op, skipping")
+				continue
+			}
+
+			// Remove "stable" tag. Multiple tags cause routes to render strangely in the final docs.
+			for i, tag := range tags {
+				if tag == "stable" {
+					log.Println("removing stable tag")
+					op["tags"] = append(tags[:i], tags[i+1:]...)
+				}
+			}
+		}
+	}
+
 	out, err := json.MarshalIndent(data, "", " ")
 	if err != nil {
 		log.Fatal(err)

pkg/services/ngalert/api/tooling/post.json

@@ -1088,6 +1088,13 @@
     "alertmanager_config": {
      "$ref": "#/definitions/GettableApiAlertingConfig"
     },
+    "template_file_provenances": {
+     "additionalProperties": {
+      "$ref": "#/definitions/Provenance"
+     },
+     "type": "object",
+     "x-go-name": "TemplateFileProvenances"
+    },
     "template_files": {
      "additionalProperties": {
       "type": "string"
@@ -3140,12 +3147,11 @@
    "x-go-package": "github.com/prometheus/alertmanager/api/v2/models"
   },
   "alertGroups": {
+   "description": "AlertGroups alert groups",
    "items": {
     "$ref": "#/definitions/alertGroup"
    },
-   "type": "array",
-   "x-go-name": "AlertGroups",
-   "x-go-package": "github.com/prometheus/alertmanager/api/v2/models"
+   "type": "array"
   },
   "alertStatus": {
    "description": "AlertStatus alert status",
@@ -3265,7 +3271,6 @@
    "$ref": "#/definitions/Duration"
   },
   "gettableAlert": {
-   "description": "GettableAlert gettable alert",
    "properties": {
     "annotations": {
      "$ref": "#/definitions/labelSet"
@@ -3324,17 +3329,19 @@
     "status",
     "updatedAt"
    ],
-   "type": "object"
+   "type": "object",
+   "x-go-name": "GettableAlert",
+   "x-go-package": "github.com/prometheus/alertmanager/api/v2/models"
   },
   "gettableAlerts": {
+   "description": "GettableAlerts gettable alerts",
    "items": {
     "$ref": "#/definitions/gettableAlert"
    },
-   "type": "array",
-   "x-go-name": "GettableAlerts",
-   "x-go-package": "github.com/prometheus/alertmanager/api/v2/models"
+   "type": "array"
   },
   "gettableSilence": {
+   "description": "GettableSilence gettable silence",
    "properties": {
     "comment": {
      "description": "comment",
@@ -3386,17 +3393,14 @@
     "status",
     "updatedAt"
    ],
-   "type": "object",
-   "x-go-name": "GettableSilence",
-   "x-go-package": "github.com/prometheus/alertmanager/api/v2/models"
+   "type": "object"
   },
   "gettableSilences": {
+   "description": "GettableSilences gettable silences",
    "items": {
     "$ref": "#/definitions/gettableSilence"
    },
-   "type": "array",
-   "x-go-name": "GettableSilences",
-   "x-go-package": "github.com/prometheus/alertmanager/api/v2/models"
+   "type": "array"
   },
   "labelSet": {
    "additionalProperties": {
@@ -3568,7 +3572,6 @@
    "type": "object"
   },
   "receiver": {
-   "description": "Receiver receiver",
    "properties": {
     "name": {
      "description": "name",
@@ -3579,7 +3582,9 @@
    "required": [
     "name"
    ],
-   "type": "object"
+   "type": "object",
+   "x-go-name": "Receiver",
+   "x-go-package": "github.com/prometheus/alertmanager/api/v2/models"
   },
   "silence": {
    "description": "Silence silence",

pkg/services/ngalert/api/tooling/spec.json

@@ -3106,6 +3106,13 @@
         "alertmanager_config": {
           "$ref": "#/definitions/GettableApiAlertingConfig"
         },
+        "template_file_provenances": {
+          "type": "object",
+          "additionalProperties": {
+            "$ref": "#/definitions/Provenance"
+          },
+          "x-go-name": "TemplateFileProvenances"
+        },
         "template_files": {
           "type": "object",
           "additionalProperties": {
@@ -5159,12 +5166,11 @@
       "$ref": "#/definitions/alertGroup"
     },
     "alertGroups": {
+      "description": "AlertGroups alert groups",
       "type": "array",
       "items": {
         "$ref": "#/definitions/alertGroup"
       },
-      "x-go-name": "AlertGroups",
-      "x-go-package": "github.com/prometheus/alertmanager/api/v2/models",
       "$ref": "#/definitions/alertGroups"
     },
     "alertStatus": {
@@ -5285,7 +5291,6 @@
       "$ref": "#/definitions/Duration"
     },
     "gettableAlert": {
-      "description": "GettableAlert gettable alert",
       "type": "object",
       "required": [
         "labels",
@@ -5345,18 +5350,20 @@
           "x-go-name": "UpdatedAt"
         }
       },
+      "x-go-name": "GettableAlert",
+      "x-go-package": "github.com/prometheus/alertmanager/api/v2/models",
       "$ref": "#/definitions/gettableAlert"
     },
     "gettableAlerts": {
+      "description": "GettableAlerts gettable alerts",
       "type": "array",
       "items": {
         "$ref": "#/definitions/gettableAlert"
       },
-      "x-go-name": "GettableAlerts",
-      "x-go-package": "github.com/prometheus/alertmanager/api/v2/models",
       "$ref": "#/definitions/gettableAlerts"
     },
     "gettableSilence": {
+      "description": "GettableSilence gettable silence",
       "type": "object",
       "required": [
         "comment",
@@ -5409,17 +5416,14 @@
           "x-go-name": "UpdatedAt"
         }
       },
-      "x-go-name": "GettableSilence",
-      "x-go-package": "github.com/prometheus/alertmanager/api/v2/models",
       "$ref": "#/definitions/gettableSilence"
     },
     "gettableSilences": {
+      "description": "GettableSilences gettable silences",
       "type": "array",
       "items": {
         "$ref": "#/definitions/gettableSilence"
       },
-      "x-go-name": "GettableSilences",
-      "x-go-package": "github.com/prometheus/alertmanager/api/v2/models",
       "$ref": "#/definitions/gettableSilences"
     },
     "labelSet": {
@@ -5593,7 +5597,6 @@
       "$ref": "#/definitions/postableSilence"
     },
     "receiver": {
-      "description": "Receiver receiver",
       "type": "object",
       "required": [
         "name"
@@ -5605,6 +5608,8 @@
           "x-go-name": "Name"
         }
       },
+      "x-go-name": "Receiver",
+      "x-go-package": "github.com/prometheus/alertmanager/api/v2/models",
       "$ref": "#/definitions/receiver"
     },
     "silence": {