# OpenAPI / Swagger

API публикует OpenAPI-документ через `Swashbuckle.AspNetCore`. Описание
включает security-scheme `Bearer` (OpenIddict JWT), стабильные
`operationId = Controller_Action`, уникальные `schemaId` с префиксом из
неймспейса (одноимённые nested record'ы в разных контроллерах не схлопываются).

## Эндпоинты

| URL | Когда |
|---|---|
| `/swagger`               | UI, только Development |
| `/swagger/v1/swagger.json` | JSON-документ, только Development |

На stage/prod swagger отключён — отдельный endpoint enumeration
не должен раскрываться неавторизованным клиентам. Если нужно — поднимать
локальный API из той же ветки.

## TypeScript-клиент

В `src/food-market.web` подключён `openapi-typescript` (devDependency).
Команда:

```bash
# Терминал 1: поднять API
ASPNETCORE_ENVIRONMENT=Development dotnet run --project src/food-market.api

# Терминал 2: сгенерировать types
cd src/food-market.web
pnpm run gen:api      # читает http://localhost:5081/swagger/v1/swagger.json
                      # → src/lib/api.generated.ts
```

Альтернативно (без живого API) — через `Swashbuckle.AspNetCore.Cli` (версия
должна совпадать с `Swashbuckle.AspNetCore`, у нас 6.9.0):

```bash
dotnet tool install --global Swashbuckle.AspNetCore.Cli --version 6.9.0
dotnet build src/food-market.api
swagger tofile --output /tmp/swagger.json \
  src/food-market.api/bin/Debug/net8.0/foodmarket.Api.dll v1
cd src/food-market.web
pnpm exec openapi-typescript /tmp/swagger.json -o src/lib/api.generated.ts
```

## Использование

Тонкая обёртка в `src/food-market.web/src/lib/apiClient.ts` экспортирует
типизированные хелперы для отчётов (Reports/Sales, Reports/ABC,
Reports/Profit) — образец постепенной миграции с ручных типов в
`types.ts`. В новом коде использовать обёртку и переэкспортированные
типы; старые страницы переписывать по мере правок.

## Версионирование

Document `v1` — единственный. Если будут breaking changes — поднимаем
`v2` рядом, не ломая `v1`. У `operationId` стабильное имя
`Controller_Action` — переименование контроллера ломает TS-клиент,
относиться как к public API.