descrybe/docs/api-surface-smoke.md

API surface smoke - admin, health, docs, public v1

When: 2026-08-04 03:03:48 +02:00
API: http://127.0.0.1:8080
Web: http://localhost:5174
Demo: demo@descrybe.local / DemoPass123! (is_platform_admin=true)
Demo API key: dk_demo_local_descrybe_test_key_v1 (Platform Demo after seed-demo; not A1)

Note (isolation): Historical matrix rows below may still say Local Demo Co / A1 — treat as outdated. Canonical identity: safe-test-fixtures.md.

Summary

Metric	Value
PASS	20
FAIL	0
Overall	PASS

Matrix

Check	Result	Detail
demo is_platform_admin	PASS	db=true
login demo platform admin	PASS	True
GET /api/auth/me platform admin	PASS	Local Demo Co
GET /api/admin/users	PASS	status=200
GET /api/admin/companies	PASS	status=200
GET /api/admin/analytics	PASS	status=200
GET /api/admin/jobs	PASS	status=200
GET /healthz	PASS	status=200
GET /readyz	PASS	status=200
GET /docs (web)	PASS	status=200
GET /api/v1/openapi.yaml	PASS	status=200
OpenAPI has auth + localhost server	PASS	clarity text present
v1 GET /products?limit=1 (demo key)	PASS	status=200
v1 GET /categories?limit=1 (demo key)	PASS	status=200
v1 GET /attributes?limit=1 (demo key)	PASS	status=200
v1 GET /feeds (demo key)	PASS	status=200
v1 GET /export-feeds (demo key)	PASS	status=200
v1 GET /process (demo key)	PASS	status=200
v1 GET /health (demo key)	PASS	status=200
v1 products without key -> 401	PASS	status=401

Fixes applied this run

1. OpenAPI clarity (apps/api/internal/httpapi/v1_openapi.go): expanded info.description with auth headers, curl example, base path notes; added http://localhost:8080/api/v1 server; ASCII-safe Bearer scheme description.
2. Docs page clarity (apps/web/src/routes/docs/+page.svelte): header link (OpenAPI YAML), loading/error/retry for RapiDoc, theme via marketingTheme.

Notes

• GET /healthz / GET /readyz are on the API host; Vite proxies them from the web origin in local dev.
• Interactive docs: http://localhost:5174/docs (RapiDoc); raw spec: /api/v1/openapi.yaml.
• Public /api/v1/* is API-key only; dashboard /api/* is session + CSRF.
• Related: demo-user.md, qa-local-demo.md, local-smoke-results.md.