feat(api): OpenAPI spec and an offline Swagger UI
- feat: internal/api/openapi/openapi.yaml describes every operation (OpenAPI 3.0.3), written by hand and embedded in the binary; GET /api/v1/openapi.yaml serves it - feat: GET /api/docs/ serves Swagger UI from assets embedded in the binary (github.com/swaggest/swgui, v5emb), so opening it never contacts another server; both are public because they contain no data - feat: response objects in the spec are closed (additionalProperties: false) - test: the spec is valid OpenAPI; the router and the spec describe the same operations in both directions; every operation has an id, a summary, a tag, a documented 401 when it needs a token and a 403 when it is admin only - test: a contract test drives every operation through the real services, including a real scan and real streaming, and validates each response (status, headers, JSON body) against the spec with kin-openapi; it fails if an operation was never exercised. Checked by breaking the code and the spec on purpose - test: the docs page loads without any external address and every asset it references is served - docs: README section on the interactive documentation and on keeping the spec in step with the code Closes #15
This commit is contained in:
parent
6d004c4225
commit
9d28a8a99c
1 changed files with 1710 additions and 4 deletions
7
go.mod
7
go.mod
|
|
@ -3,10 +3,12 @@ module codeberg.org/squidd/sonda
|
|||
go 1.27.1
|
||||
|
||||
require (
|
||||
github.com/getkin/kin-openapi v0.153.0
|
||||
github.com/gin-gonic/gin v1.12.0
|
||||
github.com/golang-jwt/jwt/v5 v5.3.1
|
||||
github.com/jackc/pgx/v5 v5.12.0
|
||||
github.com/pelletier/go-toml/v2 v2.4.3
|
||||
github.com/swaggest/swgui v1.8.9
|
||||
github.com/uptrace/bun v1.3.0
|
||||
github.com/uptrace/bun/dialect/pgdialect v1.3.0
|
||||
github.com/uptrace/bun/dialect/sqlitedialect v1.3.0
|
||||
|
|
@ -24,6 +26,8 @@ require (
|
|||
github.com/dustin/go-humanize v1.1.0 // indirect
|
||||
github.com/gabriel-vasile/mimetype v1.4.12 // indirect
|
||||
github.com/gin-contrib/sse v1.1.0 // indirect
|
||||
github.com/go-openapi/jsonpointer v0.22.5 // indirect
|
||||
github.com/go-openapi/swag/jsonname v0.25.5 // indirect
|
||||
github.com/go-playground/locales v0.14.1 // indirect
|
||||
github.com/go-playground/universal-translator v0.18.1 // indirect
|
||||
github.com/go-playground/validator/v10 v10.30.1 // indirect
|
||||
|
|
@ -45,14 +49,17 @@ require (
|
|||
github.com/quic-go/qpack v0.6.0 // indirect
|
||||
github.com/quic-go/quic-go v0.59.0 // indirect
|
||||
github.com/remyoudompheng/bigfft v0.0.0-20230129092748-24d4a6f8daec // indirect
|
||||
github.com/santhosh-tekuri/jsonschema/v6 v6.0.3 // indirect
|
||||
github.com/tetratelabs/wazero v1.11.1-0.20260428013916-2bbd517b7633 // indirect
|
||||
github.com/tmthrgd/go-hex v0.0.0-20190904060850-447a3041c3bc // indirect
|
||||
github.com/twitchyliquid64/golang-asm v0.15.1 // indirect
|
||||
github.com/ugorji/go/codec v1.3.1 // indirect
|
||||
github.com/vearutop/statigz v1.4.0 // indirect
|
||||
github.com/vmihailenco/msgpack/v5 v5.4.1 // indirect
|
||||
github.com/vmihailenco/tagparser/v2 v2.0.0 // indirect
|
||||
go.mongodb.org/mongo-driver/v2 v2.5.0 // indirect
|
||||
go.uber.org/multierr v1.11.0 // indirect
|
||||
go.yaml.in/yaml/v4 v4.0.0 // indirect
|
||||
golang.org/x/arch v0.22.0 // indirect
|
||||
golang.org/x/net v0.60.0 // indirect
|
||||
golang.org/x/sync v0.24.0 // indirect
|
||||
|
|
|
|||
Loading…
Reference in a new issue