Lamoda API Parser → Markdown

Парсер документации Lamoda с портала academy.lamoda.ru, который превращает её в локальную базу markdown-файлов: одна статья = один файл, один эндпоинт = один файл. Удобно скармливать LLM, держать в репозитории клиента, искать grep-ом и читать без браузера.

---

Что внутри

Lamoda Academy состоит из двух частей, и парсер забирает обе:

• Текстовые статьи — ~20 разделов (Подключение, Товары, Заказы, FBS, FBO, Маркировка и т.д.), конвертируются из HTML в markdown.
• OpenAPI-спецификации — три спеки (B2B Platform API, Seller Partner API, Seller Partner REST). На странице их рисует Swagger UI; парсер забирает исходный YAML и раскладывает в per-endpoint markdown.

md/
├── _README.md                                  ← глобальный индекс
├── articles/
│   ├── _README.md                              ← индекс разделов статей
│   ├── 2-podklyuchenie-k-api/
│   │   ├── _README.md                          ← индекс раздела
│   │   ├── 2_1_endpoints.md                    ← одна статья = один файл
│   │   └── 2_2_oauth.md
│   └── ...                                     ← остальные 19 разделов
└── api/
    ├── _README.md                              ← индекс OpenAPI-спек
    ├── lamoda-b2b-platform-api/
    │   ├── _README.md                          ← индекс спеки (теги + операции)
    │   ├── openapi.json                        ← сырая спека (OpenAPI 3)
    │   ├── tags/<тег>.md                       ← описание раздела
    │   └── operations/
    │       ├── Авторизация/<METHOD путь>.md    ← один файл = один эндпоинт
    │       ├── Заказы/...
    │       └── ...                             ← группировка по первому тегу
    ├── lamoda-seller-partner-api/
    └── lamoda-seller-partner-api-rest/

В каждом md-файле эндпоинта: метод, путь, теги, operationId, описание, авторизация, базовый URL, параметры (таблица), тело запроса со схемой и примерами, все коды ответов со схемами и JSON-примерами.

Текущий снимок: 2 части · 53 статьи в 20 разделах · 107 эндпоинтов в 3 спеках · 216 файлов · ~2.2 MB (b2b: 73 эндпоинта, seller-partner: 24, seller-partner-rest: 10).

---

Зачем

Документация Lamoda рендерится в браузере и разбросана по десяткам страниц. Скопировать удобный референс «в один клик» нельзя, в LLM-контекст её не положишь. А в md-формате с этим всё хорошо:

• Контекст для AI-агентов. Кладёшь нужный .md в промпт — модель пишет рабочий клиент сразу с правильными полями, заголовком Authorization: Bearer и кодами ошибок.
• Версионирование документации. Чекин репо → git diff показывает, что Lamoda сломала/добавила.
• Быстрый поиск. grep -r "client_credentials" за 0.2 секунды.
• Офлайн. Доки доступны без выхода в сеть.

---

Что внутри хитрого

1. Без playwright. Портал собран на Bitrix и отдаётся server-rendered HTML, антибота нет — хватает обычного requests. Это главное отличие от Ozon-парсера, которому нужен реальный Chrome.
2. BFS-обход дерева. Парсер обходит /articles/api/ в ширину: каждая страница это либо листинг (раздел со списком статей), либо статья, либо Swagger-страница. Классификация по разметке Bitrix.
3. Источник OpenAPI. Swagger UI грузит YAML отдельным запросом (url: "/upload/iblock/.../...yaml"); парсер вытаскивает этот URL из инлайн- скрипта и качает YAML напрямую.
4. HTML → markdown. Контент статей (div.article-detail__text) конвертируется рекурсивно: заголовки, абзацы, таблицы, списки, код-блоки (с автоопределением языка), картинки, ссылки. Декоративные <svg>-иконки отбрасываются.
5. Переписывание ссылок. Внутренние ссылки между статьями (в т.ч. относительные ../../) резолвятся и переписываются в относительные md-пути; ссылки на нескраулённые страницы остаются абсолютными URL.
6. Санитайзер YAML. PyYAML парсит ISO-даты в объекты datetime, а коды ответов (200:) — в int; перед сериализацией в JSON всё приводится к JSON-совместимым типам.
7. Резолв $ref, allOf, синтез примеров. Логика рендеринга OpenAPI портирована из Ozon Docs Parser: разворот $ref с защитой от циклов, слияние allOf, сборка JSON-примера из inline-example свойств схемы.

---

Установка

pip install -r requirements.txt

Зависимости: requests, beautifulsoup4, PyYAML. Playwright не нужен.

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

# Всё: статьи + 3 OpenAPI-спеки (по умолчанию)
python lamoda_docs_parser.py

# Только текстовые статьи
python lamoda_docs_parser.py articles

# Только OpenAPI-спеки
python lamoda_docs_parser.py api

Результат складывается в md/. Перезапуск полностью обновляет файлы. Полный прогон занимает 1.5–2 минуты (~110 HTTP-запросов с паузой между ними).

---

Пример вывода

md/articles/2-podklyuchenie-k-api/2_2_oauth.md:

# OAuth 2.0 авторизация

**Раздел:** [Подключение к API](_README.md) · **Источник:** [https://academy.lamoda.ru/...]

## Получение токена: Lamoda B2B Platform Partner API (REST)

### Запрос

​```bash
curl -X POST 'https://api-b2b.lamoda.ru/auth/token' \
  -H 'Content-Type: application/json' \
  -d '{ "client_id": "...", "grant_type": "client_credentials" }'
​```

md/api/lamoda-b2b-platform-api/operations/Авторизация/GET auth-token.md:

# GET /auth/token

**Получение токена авторизации.**

**Полный путь:** `GET https://api-b2b.lamoda.ru/auth/token`

## Параметры
| Имя | В | Тип | Обязательный | Описание |
|---|---|---|---|---|
| `client_id` | query | string | да | ID клиента |
... схема ответа + JSON-пример ...

---

Лицензия

MIT — делайте что хотите.

Документация принадлежит Lamoda; репозиторий служит лишь как конвертер формата для собственного использования.