Sourcey: автономный генератор статических порталов документации из спецификаций OpenAPI, MCP и Doxygen

В большинстве инженерных команд техническая документация разорвана на изолированные анклавы. Справочник REST API живет в Swagger UI или Redoc, низкоуровневый код на C++ или Rust документируется через Doxygen и rustdoc, архитектурные гайды хранятся в Markdown-файлах репозитория, а интеграции с языковыми моделями описываются вручную в закрытых корпоративных базах знаний. Чтобы получить цельную картину системы, новому разработчику приходится держать открытыми полдюжины разнородных вкладок.

Открытый инструмент Sourcey под лицензией AGPL-3.0 предлагает элегантный выход из этой фрагментации. Это автономный генератор документации, способный на этапе сборки объединить разрозненные форматы данных — от современных спецификаций OpenAPI до протоколов ИИ-инструментов Model Context Protocol (MCP) — в единый монолитный статический портал без внешних рантайм-зависимостей и платных подписок.

Сборка мульти-форматной документации на этапе компиляции

Ключевая архитектурная ценность Sourcey — принцип полной статической автономии (Build-Time Static Generation). Инструмент не требует развертывания баз данных или серверных бэкендов: он компилирует все входные источники в оптимизированный набор HTML-, CSS- и JS-файлов, готовых к мгновенному хостингу на GitHub Pages, Cloudflare Pages или во внутреннем защищенном контуре компании.

Генератор поддерживает широкий спектр инженерных спецификаций:

OpenAPI версий 2.0, 3.0, 3.1 и 3.2: полный разбор сложных схем JSON Schema, поддержка ссылок $ref и автоматическая генерация интерактивных примеров вызовов на десяти языках программирования.
Серверы Model Context Protocol (MCP): автоматическая визуализация инструментов, контекстных ресурсов и промптов с генерацией валидных полезных нагрузок JSON-RPC для тестирования агентов.
Исходный код системных языков: интеграция выгрузок Doxygen XML (для C++), godoc (для Go) и rustdoc JSON (для Rust).
Встроенный поиск и контекст для ИИ: клиентский нечеткий поиск (fuzzy search по шорткату Cmd+K) и автоматический экспорт сводных файлов llms.txt для чтения документации кодинг-ассистентами.

Вся архитектура портала настраивается через лаконичный файл sourcey.config.ts:

// sourcey.config.ts — централизованная конфигурация портала документации
import { defineConfig } from 'sourcey';

export default defineConfig({
  title: 'Platform Engineering Documentation',
  description: 'Единый портал API, системных руководств и инструментов MCP',
  sources: [
    // 1. Интеграция спецификации REST API на базе OpenAPI 3.1
    {
      type: 'openapi',
      path: './specs/openapi.yaml',
      route: '/api-reference',
    },
    // 2. Документирование инструментов агента по протоколу Model Context Protocol (MCP)
    {
      type: 'mcp',
      path: './mcp-servers/database-agent.json',
      route: '/mcp-tools',
    },
    // 3. Инженерные руководства в формате Markdown
    {
      type: 'markdown',
      path: './docs',
      route: '/guides',
    },
  ],
  output: {
    dir: './dist-docs',
    llmsTxt: true, // Генерация структурированного контекста для ИИ-агентов
  },
});

Сборка и локальная проверка собранного сайта выполняются парой команд:

# Сборка статического сайта и локальный предварительный просмотр
# 1. Запуск статической генерации HTML-страниц и поисковых индексов
npx sourcey build

# 2. Локальный предпросмотр результата без сторонних веб-серверов
npx sourcey serve --port 8080

Защита от вендорного локаута и готовность к агентной разработке

Популярные коммерческие платформы документации (ReadMe, GitBook, Mintlify) накладывают жесткие тарифные ограничения и требуют размещения чувствительной технической информации на сторонних серверах. Sourcey возвращает разработчикам полный контроль над своими артефактами. Статический сайт можно развернуть в закрытом контуре безопасности (air-gapped окружении), полностью исключив утечку внутренних интерфейсов.

Автоматическая генерация файлов llms.txt и llms-full.txt решает еще одну насущную задачу. Агенты кодинга (Cursor, Claude Code, Agy) могут загружать актуальное описание API целиком за один сетевой запрос, не тратя токены на обход разрозненных веб-страниц.

Инженерный вердикт

Sourcey закрывает многолетнюю брешь между справочниками API и архитектурной документацией. Для команд, создающих сложные микросервисные платформы или собственные экосистемы ИИ-инструментов, этот генератор предлагает редкое сочетание функциональности коммерческих платформ и полной свободы открытого исходного кода.