Commit graph sonda/internal/api/http/docs.go
Author SHA1 Message Date
tgiachi
a880b87a9e chore: move the module path to git.kmalloc.org/squid/sonda
Migrating hosting from Codeberg to git.kmalloc.org. Renames the
module path in go.mod, every internal import, and the OCI image
source label in the Dockerfile. Build and full test suite verified
green after the rename.
2026-11-15 17:30:29 +01:00
tgiachi
2ae4aedac0 fix(api): make the spec say what the code does, and make the tests prove it
- fix(spec): album.artist and track.album are real nullable objects (OpenAPI
  3.0 only honours nullable next to a type); the stream documents 304 on HEAD,
  412, If-Unmodified-Since and multipart/byteranges answers
- fix(spec): passwords and idempotency keys are measured in bytes, an overlap
  between libraries is a 400, a library PATCH needs a name or a path, limit 0
  means the default, login has no format rules of its own, and the wording about
  signing out says that issued access tokens live until they expire
- fix(auth): the Bearer scheme is matched ignoring case (RFC 7235)
- fix(listening): a listen with the access token of a deleted account is a 401
  instead of a database error
- fix(docs): the docs pages answer HEAD and carry X-Frame-Options, a CSP
  frame-ancestors, nosniff and no-referrer, since people paste their token there
- test: error codes are asserted in every error case; every accepted request is
  validated against the spec too; HEAD and 3xx answers are checked by hand
  because the validator skips them; the stream Content-Type must be one the
  spec lists; a scan held mid-way proves the scan_running conflicts; null album
  and null album artist, a vanished file, multi-range, 412 and HEAD 304 are
  exercised. Verified by breaking the code and the spec on purpose
2026-11-11 14:46:28 +01:00
tgiachi
9d28a8a99c 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
2026-11-11 14:35:16 +01:00