mirror of
https://github.com/grafana/grafana.git
synced 2025-02-25 18:55:37 -06:00
Alerting: Unify Swagger/OpenAPI generation tooling (#46928)
* Unify makefiles * Improve documentation
This commit is contained in:
parent
6565d0ee64
commit
502cf8b37f
@ -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
|
1
pkg/services/ngalert/api/tooling/.gitignore
vendored
Normal file
1
pkg/services/ngalert/api/tooling/.gitignore
vendored
Normal file
@ -0,0 +1 @@
|
||||
go/
|
@ -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
|
||||
|
@ -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.
|
||||
|
Loading…
Reference in New Issue
Block a user