From 59fb8e2b4cc2f8dd1e1ec7f6fb56b50a01e1dd47 Mon Sep 17 00:00:00 2001 From: Michael Mayer Date: Mon, 22 Sep 2025 10:56:34 +0200 Subject: [PATCH] API: Update Swagger usage notes Signed-off-by: Michael Mayer --- AGENTS.md | 12 +++++++++++- CODEMAP.md | 6 +++++- 2 files changed, 16 insertions(+), 2 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 7a06876cb..ca44cebb6 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -293,7 +293,17 @@ The following conventions summarize the insights gained when adding new configur - Portal mode: set `PHOTOPRISM_NODE_ROLE=portal` and `PHOTOPRISM_JOIN_TOKEN`. - Pagination defaults: for new list endpoints, prefer `count` default 100 (max 1000) and `offset` ≥ 0; document both in Swagger and validate bounds in handlers. - Document parameters explicitly in Swagger annotations (path, query, and body) so `make swag` produces accurate docs. - - Swagger: `make fmt-go swag-fmt && make swag` after adding or changing API annotations. +- Swagger: `make fmt-go swag-fmt && make swag` after adding or changing API annotations. + +### Swagger & API Docs + +- Annotations live next to handlers in `internal/api/*.go`. Only annotate public handlers that are registered in `internal/server/routes.go`. +- Always include the full prefix in `@Router` paths: `/api/v1/...` (not relative segments). +- Avoid annotating internal helpers (e.g., generic link creators) to prevent generating undocumented placeholder paths. +- Generate docs locally with: + - `make swag-fmt` (formats annotations) + - `make swag-json` (generates `internal/api/swagger.json` and then runs `swaggerfix` to remove unstable `time.Duration` enums for deterministic diffs) +- `time.Duration` fields are represented as integer nanoseconds in the API. The Makefile target `swag-json` automatically post-processes `swagger.json` to strip duplicated enums for this type. - Focused tests: `go test ./internal/api -run Cluster -count=1` (or limit to the package you changed). - Registry & secrets diff --git a/CODEMAP.md b/CODEMAP.md index edc949658..f3cc3aa39 100644 --- a/CODEMAP.md +++ b/CODEMAP.md @@ -44,6 +44,10 @@ HTTP API - Handlers live in `internal/api/*.go` and are registered in `internal/server/routes.go`. - Annotate new endpoints in handler files; generate docs with: `make fmt-go swag-fmt && make swag`. - Do not edit `internal/api/swagger.json` by hand. +- Swagger notes: + - Use full `/api/v1/...` in every `@Router` annotation (match the group prefix). + - Annotate only public handlers; skip internal helpers to avoid stray generic paths. + - `make swag-json` runs a stabilization step (`swaggerfix`) removing duplicated enums for `time.Duration`; API uses integer nanoseconds for durations. - Common groups in `routes.go`: sessions, OAuth/OIDC, config, users, services, thumbnails, video, downloads/zip, index/import, photos/files/labels/subjects/faces, batch ops, cluster, technical (metrics, status, echo). Configuration & Flags @@ -211,7 +215,7 @@ Useful Make Targets (selection) See Also - AGENTS.md (repository rules and tips for agents) - Developer Guide (Setup/Tests/API) — links in AGENTS.md → Sources of Truth -- Specs: `specs/dev/backend-testing.md`, `specs/portal/README.md` +- Specs: `specs/dev/backend-testing.md`, `specs/dev/api-docs-swagger.md`, `specs/portal/README.md` Fast Test Recipes - Filesystem + archives (fast): `go test ./pkg/fs -run 'Copy|Move|Unzip' -count=1`