Julien Duchesne
c9211fbd69
* ngalert openapi: Use same `basePath` as rest of Grafana Currently, there are two issues that prevent easily merging `ngalert` and grafana openapi specs: - The basePath is different. `grafana` has `/api` and `ngalert` has `/api/v1`. I changed `ngalert` to use `/api` - The `ngalert` endpoints have their basePath in the each operation path. The basePath should actually be omitted --------- Co-authored-by: Yuriy Tseretyan <yuriy.tseretyan@grafana.com>
29 lines
1.5 KiB
Markdown
29 lines
1.5 KiB
Markdown
## What
|
|
|
|
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` - 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.
|
|
|
|
### 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 /provisioning/contact-points provisioning stable RouteGetContactpoints
|
|
```
|