fix(s28): api-reference handle ~/path ASP.NET convention

ASP.NET Core convention для HttpX-атрибутов: `~/path` означает
'absolute from root, ignore class [Route]'. До фикса генератор клеил
`base-route` + `~/path` → невалидный `/~/connect/token`.

Теперь tilde корректно срезается, /connect/token виден в reference.

Также добавлен unit test ApiReferenceDocsJobTests (Sprint 28) для
lock-down regex behavior на double-nested generics.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

docs/api-reference.md

@@ -55,7 +55,7 @@ Base route: `/api/auth`
 
 | Method | Route | Permission | Summary |
 |---|---|---|---|
-| POST | `/~/connect/token` | — |  |
+| POST | `/connect/token` | — |  |
 
 ## `CounterpartiesController`
 Base route: `/api/catalog/counterparties`

scripts/gen-api-reference.py

@@ -125,6 +125,12 @@ def main() -> int:
                 if auth_m:
                     perm = f'auth:{auth_m.group(1) or "any"}'
             # Compose full route.
+            # ASP.NET Core convention: `~/path` в HttpX-атрибуте означает
+            # "absolute from root, ignore class-level [Route]". Срезаем `~`
+            # и используем sub как абсолютный путь.
+            if sub.startswith('~/'):
+                full = sub[1:]  # `~/connect/token` → `/connect/token`
+            else:
                 parts = [p.strip('/') for p in (base, sub) if p]
                 full = '/' + '/'.join(parts)
             full = full.rstrip('/') or '/'

src/food-market.api/Background/ApiReferenceDocsJob.cs

@@ -132,7 +132,20 @@ private static IEnumerable<EndpointInfo> ScanDir(string dir)
                 if (!http.Success) continue;
                 var httpMethod = http.Groups[1].Value.ToUpperInvariant();
                 var subRoute = http.Groups[2].Success ? http.Groups[2].Value : "";
-                var fullRoute = "/" + string.Join("/", new[] { baseRoute, subRoute }.Where(s => !string.IsNullOrEmpty(s))).Trim('/');
+                // Sprint 28: ASP.NET Core convention `~/path` означает "absolute
+                // from root, ignore class [Route]". Без обработки `~` попадал
+                // в начало пути и получался невалидный `/~/connect/token`.
+                string fullRoute;
+                if (subRoute.StartsWith("~/", StringComparison.Ordinal))
+                {
+                    fullRoute = subRoute[1..]; // `~/connect/token` → `/connect/token`
+                }
+                else
+                {
+                    fullRoute = "/" + string.Join("/",
+                        new[] { baseRoute, subRoute }
+                            .Where(s => !string.IsNullOrEmpty(s))).Trim('/');
+                }
 
                 var permMatch = Regex.Match(attrs, @"\[RequiresPermission\(""([^""]+)""\)\]");
                 var perm = permMatch.Success ? permMatch.Groups[1].Value : "";