fibgen: генератор OpenAPI-спеки для Fiber без единой аннотации в коде

Разработчик под ником nyawave опубликовал описание инструмента fibgen — генератора OpenAPI-спецификации для Go-фреймворка Fiber. Инструмент работает без единой аннотации в исходном коде: он обходит AST проекта, находит регистрации маршрутов и тела хендлеров, а затем строит полноценный openapi.yaml. Установка и запуск — две команды в терминале.

Почему аннотации — это технический долг

Стандартный подход к документированию Fiber-API выглядит так: над каждым хендлером пишется блок godoc-комментариев для swaggo — восемь строк на одну ручку. Проблема не в многословности, а в том, что компилятор эти комментарии не проверяет.

Разработчик переименовал поле в структуре, забыл обновить аннотацию — спека начала врать. Линтер промолчит, CI пройдёт, а фронтенд или API Gateway получат неверный контракт. Документация, которая расходится с кодом, хуже её отсутствия: ей доверяют.

Альтернативы в экосистеме Go — huma, fuego, oapi-codegen — работают хорошо, но требуют переписать хендлеры под типизированную сигнатуру вида func(ctx, In) (Out, error). В Fiber сигнатура хендлера не содержит ничего о типах запроса и ответа — они живут внутри тела функции как локальные переменные.

Рантайм-рефлексия здесь бесполезна: с точки зрения reflect все хендлеры проекта имеют один и тот же тип. Значит, нужен статический анализ — заходить прямо в тело функции.

Как работает статический анализ

fibgen загружает проект через go/packages и go/types — тем же тайпчекером, которым его собирает компилятор — и проходит по AST в несколько шагов.

Маршруты. Инструмент находит вызовы app.Get, app.Post, app.Add и разворачивает вложенные группы. Префикс app.Group("/api/v1").Group("/users") превращается в /api/v1/users. Префиксы резолвятся и через переменные, и через роутеры, переданные параметром — func RegisterUserRoutes(r fiber.Router).

Файберовский синтаксис путей переводится в OpenAPI-нотацию: :id становится {id}, :id? — необязательным параметром, :id<int> — параметром с типом integer.

Тело хендлера. Из тела функции извлекаются тело запроса через c.BodyParser и c.Bind().Body; query-параметры — как структурой, так и поштучно через c.Query, c.QueryInt, c.QueryBool; path-параметры из шаблона маршрута с уточнением типа по коду; заголовки через c.Get.

Ответы. c.JSON(x) даёт статус 200 со схемой x. c.Status(code).JSON(x) — статус берётся из code, причём как из литерала 201, так и из константы fiber.StatusCreated.

Ad-hoc объекты через fiber.Map. Формально это map[string]any, но fibgen разворачивает литерал в схему с конкретными полями. Выражение fiber.Map{"message": "ok", "data": user} превращается в объект с message типа string и data как ссылка на схему User.

Несколько форм ответа на один статус. Если хендлер отдаёт короткий объект при одном условии и полный при другом — оба варианта с одним статусом 200 собираются в oneOf.

Enum из констант. Если в коде есть именованный тип и группа констант этого типа, fibgen автоматически распознаёт это как enum и прописывает его в схему. Никаких аннотаций не нужно — информация уже есть в коде.

Детерминированный вывод. Если спека коммитится в репозиторий — а это правильная практика, позволяющая ревьюить изменения контракта вместе с кодом — порядок ключей в YAML должен быть стабильным. Мапы в Go итерируются в произвольном порядке, поэтому первая версия давала разный вывод от запуска к запуску, и диффы выглядели как полная перезапись файла. Автор ввёл отдельный тип с упорядоченной по вставке мапой и рендерит всё через неё.

Ограничения и дорожная карта

Автор честно перечисляет границы инструмента — и это отдельный плюс.

Межпроцедурный анализ отсутствует: если вместо прямого c.JSON(user) используется хелпер respondJSON(c, 200, user), тип ответа не восстановится. Это первый приоритет для развития проекта.

Динамические пути — если путь собирается из неконстантной строки, маршрут пропускается с предупреждением в stderr. Хендлеры за DI-контейнером или интерфейсом, которые невозможно статически свести к функции, получают дефолтный ответ 200. Дженерики в типах ответа поддерживаются ограниченно.

Описания и summary в спеке отсутствуют — их неоткуда взять без чтения комментариев. Это сознательный выбор автора: либо ноль аннотаций, либо человекочитаемые описания. Всё, что анализатор не смог разрешить, выводится в stderr как note — пользователь видит, где спека неполна. Подавляется флагом -quiet.

Инструмент поддерживает Fiber v2 и v3, OpenAPI 3.0 и 3.1, вывод в YAML или JSON. В репозитории лежат два примера-проекта, на которых гоняются тесты — сгенерированные документы валидируются через kin-openapi.

Для Go-команд, которые работают с Fiber и хотят держать спеку в репозитории без ручного сопровождения аннотаций, fibgen закрывает реальную боль. Проект молодой и открыт для контрибьюта: автор ждёт issue с минимальными примерами на паттерны, которые инструмент пока не покрывает. Репозиторий доступен на GitHub по адресу github.com/nyawave/fibgen, лицензия MIT.

— По материалам Хабр / Разработка: оригинальная статья. Перевод и адаптация — редакция Digital Business.