apps/photoprism
1
0
Fork 0
mirror of https://github.com/photoprism/photoprism.git synced 2025-09-26 12:51:31 +08:00
Code Issues Packages Projects Releases Wiki Activity

API: Update Swagger usage notes

Browse Source 
Signed-off-by: Michael Mayer <michael@photoprism.app>
This commit is contained in:
Michael Mayer
2025-09-22 10:56:34 +02:00
parent 8930cb7b79
commit 59fb8e2b4c
2 changed files with 16 additions and 2 deletions
Download Patch File Download Diff File Expand all files Collapse all files

12
AGENTS.md
View File

@@ -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

6
CODEMAP.md
View File

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