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