Документы и версии

Документ — это размещённое представление одного API. Он принадлежит организации, при необходимости — проекту внутри неё, и со временем накапливает версии вместо перезаписи.

Иерархия

Organization -> Project -> Document -> Versions

Документы можно создавать непосредственно в организации или внутри проекта. Списки документов доступны на обоих уровнях.

Жизненный цикл

Документ может находиться в четырёх состояниях:

Состояние	Значение	Публичные сервисы
ACTIVE	Активен	Документация и MCP доступны, если включены соответствующими настройками
PAUSED	Временно приостановлен	Публичные сервисы недоступны
ARCHIVED	Сохранён, но не считается текущим	Не обслуживается
DELETED	Логически удалён	Не обслуживается

Допустимые переходы:

pause:    ACTIVE  -> PAUSED
resume:   PAUSED  -> ACTIVE
archive:  ACTIVE / PAUSED -> ARCHIVED
restore:  ARCHIVED -> ACTIVE
delete:   ACTIVE / PAUSED / ARCHIVED -> DELETED

Приостановка — самый быстрый способ временно отключить документ и затем вернуть его в работу. Архивация сохраняет историю, но исключает документ из текущих. Удаление логическое: основные данные не уничтожаются сразу.

Версии неизменяемы

При изменении спецификации создаётся новая версия. Исходная версия никогда не заменяется:

v1 -> v2 -> v3 -> v4

Для каждой версии сохраняются:

• Ключ хранения файла в объектном хранилище;
• Контрольная сумма SHA-256;
• Тип содержимого, размер и время создания.

Это позволяет хранить историю, возвращаться к предыдущим версиям, сравнивать изменения и повторно генерировать документацию и MCP для конкретной версии.

Ссылки на текущую и закреплённую версии

• Ссылка на текущий документ всегда ведёт к последней версии;
• Ссылка на закреплённую версию указывает на конкретную версию: её содержимое не меняется для читателя.

Используйте закреплённые ссылки, когда нужен неизменяемый источник, например в описании выпуска или контракте. Ссылка на текущий документ подходит, когда всегда нужна последняя версия.

Источники

Содержимое поступает из источника. Этот уровень абстракции отделяет модель документа от конкретного способа получения данных — загрузки или Git.

• Загрузка — добавление файла напрямую;
• Git — подключение репозитория с указанием URL, ветки и пути к файлу.

Для источника Git сохраняются состояние синхронизации и время последнего выполнения. Можно:

• Подключить репозиторий: URL и путь к файлу обязательны, ветка необязательна;
• Синхронизировать по запросу, получив последнее содержимое в виде новой версии.

Метаданные источника хранятся вместе с документом: всегда можно узнать, загружен ли файл вручную или получен из репозитория, и проверить последнюю синхронизацию.

Хранение

Файлы находятся в объектном хранилище со структурой «организация / документ / версия». База данных содержит только метаданные: ключ хранения, контрольную сумму, тип содержимого и размер. По умолчанию файлы нельзя читать напрямую из хранилища без авторизации: публичный доступ осуществляется через маршруты публикации документа.

Практическая польза

Неизменяемые версии и логическое удаление позволяют быстро вносить изменения, сохраняя историю и не публикуя случайно документ, который требовалось отключить. Приостанавливайте документ для временного отключения, архивируйте для длительного хранения и закрепляйте версии в ссылках, когда нужна стабильность.

См. также: Публикуемые операции, Управление доступом, Собственные домены.