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:
Alexander Weaver 2022-05-23 14:08:27 -05:00 committed by GitHub
parent 7cd034f33a
commit ac8951f689
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
8 changed files with 3811 additions and 34 deletions

View File

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

View File

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

View File

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

View File

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

File diff suppressed because it is too large Load Diff

View File

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

View File

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

View File

@ -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": {