mirror of
https://github.com/grafana/grafana.git
synced 2025-02-25 18:55:37 -06:00
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
This commit is contained in:
parent
7cd034f33a
commit
ac8951f689
6
Makefile
6
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)
|
||||
|
3
pkg/services/ngalert/api/tooling/.gitignore
vendored
3
pkg/services/ngalert/api/tooling/.gitignore
vendored
@ -1 +1,2 @@
|
||||
go/
|
||||
go/
|
||||
spec-stable.json
|
||||
|
@ -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
|
||||
|
@ -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
|
||||
```
|
||||
|
3715
pkg/services/ngalert/api/tooling/api.json
Normal file
3715
pkg/services/ngalert/api/tooling/api.json
Normal file
File diff suppressed because it is too large
Load Diff
@ -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)
|
||||
|
@ -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",
|
||||
|
@ -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": {
|
||||
|
Loading…
Reference in New Issue
Block a user