Rewrite refs¶
Зачем¶
OpenAPI и JSON Schema специфы из контрактных репозиториев часто используют
кросс-директорные $ref:
# orchestrator/manual_session.swagger.yml
allOf:
- $ref: '../common/workspace.swagger.yml#/components/schemas/RuntimeWorkspaceConfig'
go-project-starter копирует все файлы из path: плоско в одну
директорию (api/rest/<transport>/<version>/ для REST, api/schema/<name>/
для JSON Schema). После такой копии ../common/ указывает на несуществующий
путь, и ogen / go-jsonschema падают на резолве $ref.
Флаг rewrite_refs: true включает пост-обработку: после CopySpecs /
CopySchemas стартер сканирует целевую директорию и переписывает все
$ref, у которых basename(<path>) совпадает с одним из скопированных
sibling-файлов:
# Было (в source-репо)
$ref: '../common/workspace.swagger.yml#/components/schemas/X'
# Стало (в api/rest/<svc>/v1/)
$ref: ./workspace.swagger.yml#/components/schemas/X
Поведение по умолчанию (rewrite_refs: false или поле отсутствует) — без
изменений: специфы копируются как есть.
Включение¶
REST:
rest:
- name: api
version: v1
rewrite_refs: true
path:
- "git+ssh://git@github.com/org/contracts.git#orchestrator/manual_session.swagger.yml"
- "git+ssh://git@github.com/org/contracts.git#common/workspace.swagger.yml"
JSON Schema:
jsonschema:
- name: events
rewrite_refs: true
schemas:
- id: order
path: ./schemas/order.json
- id: shared
path: ./schemas/shared.json
Что переписывается¶
evaluateRef применяется к каждому $ref значению:
| Вход | Результат | Почему |
|---|---|---|
#/components/schemas/X |
без изменений | внутренний указатель |
https://example.com/x.yaml#/X |
без изменений, warn | абсолютный URL |
foo.yaml#/X |
без изменений | уже плоский |
./foo.yaml#/X |
без изменений | уже плоский |
../common/foo.yaml#/X (sibling существует) |
./foo.yaml#/X |
sibling найден в target-директории |
../missing/foo.yaml#/X (sibling нет) |
без изменений, warn | sibling не найден — оставлено как есть |
sub/foo.yaml#/X (sibling существует) |
./foo.yaml#/X |
sibling найден |
Защита через whitelist¶
Стартер передаёт rewriter список ожидаемых basename-ов
(Transport.SpecTargetFiles / JSONSchema.SchemaTargetFiles). Если в
target-директории есть файл, который совпадает по basename с $ref, но НЕ
входит в этот список (например, пользовательский файл, оставленный там
вручную), rewriter его игнорирует и пишет warning. Это защищает от
случайной перепиcи на не-сгенерированный файл.
Поддерживаемые форматы¶
.yaml,.yml— черезgopkg.in/yaml.v3(yaml.Node); комментарии и порядок ключей сохраняются. Известное ограничение: round-trip может нормализовать стиль кавычек ('↔"). Семантика не меняется..json— через line-regex по"$ref": "...". JSON не допускает multi-line строк или комментариев, поэтому regex безопасен.
Ограничения v1¶
- Только REST (ogen / ogen_client) и JSON Schema. gRPC/proto имеет другой механизм импортов и в эту фичу не входит.
- Rewriting, не bundling. Если нужен один self-contained файл со всеми inline-схемами — это отдельная задача.
- Сканирование non-recursive: только верхний уровень target-директории.
- При коллизии basename выигрывает файл, который попал в whitelist
(
SpecTargetFiles). Если файлы из разных source-директорий с одинаковым именем (common.swagger.ymlиз двух разных путей) — стартер уже на этапе copy перезапишет один другим, так что реальной коллизии в target-директории не возникает.
Миграция с regen-cleanup.sh¶
Если у consumer-сервиса есть скрипт вида:
— после включения rewrite_refs: true в project.yaml этот блок можно
удалить. Стартер сам перепишет $ref сразу после copy, до запуска ogen.