Alexander Weaver
19 lines
1.1 KiB
Markdown
19 lines
1.1 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.
|