swagger + agents

documentation/reverse-proxy-swagger.md

@@ -0,0 +1,49 @@
+# Reverse proxy a Swagger (ROOT_PATH)
+
+Tato služba běží v AppFactory za reverzní proxy (Caddy) na veřejné cestě:
+
+```text
+https://services.csbot.cz/apps/idoklad
+```
+
+## Jak Caddy předává requesty
+
+Caddy používá `handle_path`, který prefix `/apps/idoklad` **odstraní** dříve, než
+request dorazí do containeru. Container tedy přijímá routy bez prefixu:
+
+```text
+veřejně:   GET /apps/idoklad/contacts
+container: GET /contacts
+```
+
+Důsledek: `HttpRequest.PathBase` je uvnitř containeru **prázdný**, protože příchozí
+cesta už prefix neobsahuje. Nelze z něj proto odvodit veřejnou cestu pro OpenAPI.
+
+## Konfigurace v `Program.cs`
+
+- `ROOT_PATH` (env, např. `/apps/idoklad`) je jediný spolehlivý zdroj veřejného prefixu.
+- Z `ROOT_PATH` se sestaví `publicPrefix` (normalizovaný, s úvodním lomítkem).
+- `UsePathBase(publicPrefix)` je za `handle_path` no-op, ale ponechán pro případ proxy,
+  která prefix nestrhává (`handle`), aby routy stále seděly.
+- OpenAPI `servers[0].url` se v `PreSerializeFilters` nastaví na `publicPrefix`
+  (fallback na `PathBase`, nakonec `/` pro lokální běh).
+
+Díky tomu Swagger UI „Try it out" volá `…/apps/idoklad/<endpoint>`, ne kořen domény.
+
+## Ověření
+
+| Kontrola | Lokálně (bez ROOT_PATH) | S `ROOT_PATH=/apps/idoklad` |
+|---|---|---|
+| `GET /health` | 200 | 200 |
+| `GET /docs` (Swagger UI) | 200 | 200 |
+| `GET /docs/v1/swagger.json` | 200 | 200 |
+| `servers[0].url` v OpenAPI | `/` | `/apps/idoklad` |
+
+Veřejně po deploy ověř:
+
+```text
+GET https://services.csbot.cz/apps/idoklad/health
+GET https://services.csbot.cz/apps/idoklad/docs
+```
+
+a ve Swagger UI, že „Try it out" cílí na `https://services.csbot.cz/apps/idoklad/<endpoint>`.