Alerting: Unify Swagger/OpenAPI generation tooling (#46928)

* Unify makefiles

* Improve documentation

pkg/services/ngalert/api/Makefile

@@ -1,28 +0,0 @@
-.DEFAULT_GOAL := all
-
-GENERATED_GO_MATCHERS = ./go/*.go
-
-swagger-codegen-api:
-	docker run --rm -v $$(pwd):/local --user $$(id -u):$$(id -g) swaggerapi/swagger-codegen-cli generate \
-	-i /local/tooling/post.json \
-	-l go-server \
-	-Dapis \
-	-o /local \
-	--additional-properties packageName=api \
-	-t /local/tooling/swagger-codegen/templates \
-	# --import-mappings eval.RelativeTimeRange="github.com/grafana/grafana/pkg/services/ngalert/eval" \
-	# --type-mappings RelativeTimeRange=eval.RelativeTimeRange
-
-copy-files:
-	ls -1 go | xargs -n 1 -I {} mv go/{} generated_base_{}
-
-fix:
-	sed -i -e 's/apimodels\.\[\]PostableAlert/apimodels.PostableAlerts/' $(GENERATED_GO_MATCHERS)
-	sed -i -e 's/apimodels\.\[\]UpdateDashboardAclCommand/apimodels.Permissions/' $(GENERATED_GO_MATCHERS)
-	sed -i -e 's/apimodels\.\[\]PostableApiReceiver/apimodels.TestReceiversConfigParams/' $(GENERATED_GO_MATCHERS)
-	goimports -w -v $(GENERATED_GO_MATCHERS)
-
-clean:
-	rm -rf ./go
-
-all: swagger-codegen-api fix copy-files clean

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

@@ -0,0 +1 @@
+go/

pkg/services/ngalert/api/tooling/Makefile

@@ -7,6 +7,10 @@ SWAGGER_TAG ?= latest
 PATH_DOWN = pkg/services/ngalert/api/tooling
 PATH_UP = ../../../../..
 
+.DEFAULT_GOAL := all
+
+GENERATED_GO_MATCHERS = ./go/*.go
+
 spec.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
@@ -25,6 +29,30 @@ spec.json-mac: ensure_go-swagger_mac $(GO_PKG_FILES)
 post.json: spec.json
 	go run cmd/clean-swagger/main.go -if $(<) -of $@
 
-.PHONY: openapi
+swagger-codegen-api:
-openapi: post.json
+	docker run --rm -v $$(pwd):/local --user $$(id -u):$$(id -g) swaggerapi/swagger-codegen-cli generate \
+	-i /local/post.json \
+	-l go-server \
+	-Dapis \
+	-o /local \
+	--additional-properties packageName=api \
+	-t /local/swagger-codegen/templates \
+	# --import-mappings eval.RelativeTimeRange="github.com/grafana/grafana/pkg/services/ngalert/eval" \
+	# --type-mappings RelativeTimeRange=eval.RelativeTimeRange
+
+copy-files:
+	ls -1 go | xargs -n 1 -I {} mv go/{} ../generated_base_{}
+
+fix:
+	sed -i -e 's/apimodels\.\[\]PostableAlert/apimodels.PostableAlerts/' $(GENERATED_GO_MATCHERS)
+	sed -i -e 's/apimodels\.\[\]UpdateDashboardAclCommand/apimodels.Permissions/' $(GENERATED_GO_MATCHERS)
+	sed -i -e 's/apimodels\.\[\]PostableApiReceiver/apimodels.TestReceiversConfigParams/' $(GENERATED_GO_MATCHERS)
+	goimports -w -v $(GENERATED_GO_MATCHERS)
+
+clean:
+	rm -rf ./go
+
+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	

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

@@ -1,13 +1,18 @@
 ## What
 
-[view api](http://localhost)
+This aims to define the unified alerting API as code. It generates OpenAPI definitions from go structs. It also generates server/route stubs based on our documentation.
-
-This aims to define the unified alerting API as code. It generates OpenAPI definitions from go structs
-
 
 ## Running
 
-`make openapi`
+`make` - regenerate everything - documentation and server stubs.
+`make serve` - regenerate the Swagger document, and host rendered docs on port 80. [view api](http://localhost)
 
 ## Requires
  - [go-swagger](https://github.com/go-swagger/go-swagger)
+ - [goimports](https://pkg.go.dev/golang.org/x/tools/cmd/goimports)
+
+## Why
+
+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.