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

* Unify makefiles

* Improve documentation
This commit is contained in:
Alexander Weaver 2022-03-31 02:34:46 -05:00 committed by GitHub
parent 6565d0ee64
commit 502cf8b37f
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
4 changed files with 41 additions and 35 deletions

View File

@ -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

View File

@ -0,0 +1 @@
go/

View File

@ -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
openapi: post.json
swagger-codegen-api:
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

View File

@ -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
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.
## 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.