Соглашение по ведению документации

Это соглашение определяет единый порядок подготовки и обновления документации по REGOS: API.

1. Область действия

Соглашение обязательно для:

  • документации эндпоинтов в docs/**;
  • примеров запросов и ответов;
  • описаний ограничений, валидаций и ошибок;
  • changelog и технических заметок по API.

2. Источник истины

Источник истины для API-контракта:

  • контроллеры (Controllers);
  • модели запроса/ответа (Models);
  • бизнес-ограничения и фактическое поведение (Persistents, Middleware, Global).

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

3. Когда документацию нужно обновлять обязательно

Документация обновляется в том же PR/коммите, если изменилось хотя бы одно из:

  • маршрут, HTTP-метод, базовый путь;
  • состав/типы полей запроса или ответа;
  • обязательность параметров;
  • лимиты, значения по умолчанию, диапазоны (кроме параметров, задаваемых серверными настройками);
  • правила валидации;
  • коды/сценарии ошибок;
  • бизнес-поведение метода;
  • требования доступа (права, ограничения по роли).
  • файлы миграций БД (db_updates/*.sql) или реестр версий миграций.

Правила по changelog:

  • changelog обновляется при каждом изменении, влияющем на API-контракт, поведение методов, ошибки, миграции БД или rollout.
  • изменения за одну дату накапливаются в одной записи (в одном блоке даты/версии), а не создаются разрозненными дубликатами.
  • при добавлении/изменении миграции в changelog обязательно указывать факт миграции и номер версии/диапазон версий.
  • публичный changelog docs/01.intro/08.changelog/default.ru.md содержит только публично значимые изменения API (без деталей внутренних процессов, инфраструктуры и технического рефакторинга).
  • полный внутренний лог изменений ведётся в Regos_API/change_log.txt и включает все изменения, в том числе внутренние технические детали.
  • при каждом изменении обновляются оба лога: публичный (в сжатом публичном виде) и внутренний (с полной детализацией).
  • версия и дата релиза в верхнем блоке публичного и внутреннего логов должны совпадать между собой и соответствовать версии приложения в Regos_API/Regos_API.csproj.

Примечание: параметры, зависящие от серверной конфигурации (например, query_limit, пороги поиска и иные значения из ServerSettings), не документируются как фиксированные числовые константы. Для них используется формулировка «определяется серверными настройками».

4. Минимальный состав страницы эндпоинта

Каждая страница метода должна содержать:

  • HTTP-метод + путь (в полном виде, например POST /v1/Brand/Get);
  • краткое назначение метода;
  • таблицу входных параметров:
    • имя, тип, обязательность, ограничения, описание;
  • таблицу выходных параметров:
    • имя, тип, описание;
  • для полей enum: перечень допустимых значений в строковом виде;
  • для сложных типов (Object, Array of Object, вложенные модели): перекрёстные ссылки на страницы соответствующих моделей;
  • для методов массового изменения (Add/Edit/Delete и аналогичные batch-операции): result.ids с массивом ID фактически изменённых записей (в дополнение к row_affected);
  • минимум один валидный JSON-пример запроса;
  • минимум один валидный JSON-пример успешного ответа;
  • при нетривиальной валидации: примеры ошибок.

5. Правила оформления

  • Язык документации: русский (default.ru.md), при необходимости синхронно обновляется другая локаль.
  • Термины и имена полей указываются в точности как в API (snake_case, регистр сохраняется).
  • Типы (Int64, Int32, String, Array) должны совпадать с фактической сериализацией.
  • На уровне API прикладные ошибки документируются в формате HTTP 200 + ErrorResult (а не через 4xx/5xx).
  • enum в документации всегда указывается как String (строковое значение), а не как числовой код.
  • Для каждого enum указывать список допустимых строковых значений.
  • В JSON-примерах значения enum указывать строками.
  • Для всех используемых моделей в описании методов обязательно указывать перекрёстные ссылки на их страницы в документации.
  • Базовый публичный домен документации: https://docs.regos.uz/ru/api.
  • Предпочтительный формат внутренних ссылок: относительные пути (например, ../, ../../references/item, ./get).
  • Полные URL использовать только для внешних ресурсов или когда относительная ссылка невозможна.
  • Описания должны быть конкретными: без общих формулировок, с явными ограничениями.
  • Параметры, управляемые серверной конфигурацией, описываются как конфигурируемые; конкретные значения не фиксируются в документации.
  • В примерах не использовать фиктивные поля, которых нет в контракте.
  • Для методов массового изменения использовать единый формат успешного ответа: row_affected + ids.
  • ids должен содержать ID именно тех записей, которые были изменены в рамках вызова метода.
  • Если конкретный legacy-метод пока возвращает только row_affected, это должно быть явно отмечено в документации метода как временное ограничение с планом унификации.

6. Правила актуальности

  • При каждом изменении страницы обновляется sitemap.lastmod.
  • Дата lastmod должна соответствовать фактической дате изменения контента.
  • Если контракт изменён, но документация не обновлена, изменение считается незавершённым.
  • Если изменение затрагивает несколько разделов docs, актуализируются все связанные страницы (метод, модель, intro-разделы, ошибки, лимиты, changelog).

7. Обратная совместимость и breaking changes

  • Для breaking changes обязательно:
    • явная пометка в changelog;
    • описание миграции;
    • указание даты вступления изменения в силу.
  • Временные совместимые маршруты/поля помечаются как deprecated с планом удаления.

8. Чек-лист перед публикацией

Перед слиянием изменений проверить:

  • маршрут и метод совпадают с контроллером;
  • входные/выходные типы совпадают с моделями;
  • enum задокументированы как строковые типы и имеют список допустимых строковых значений;
  • для используемых моделей добавлены рабочие перекрёстные ссылки;
  • для методов массового изменения в ответе задокументированы и показаны в примере оба поля: row_affected и ids;
  • changelog обновлён в рамках текущей даты/версии без создания дублирующих блоков;
  • публичный changelog (docs/01.intro/08.changelog/default.ru.md) не содержит внутренних технических деталей;
  • внутренний лог (Regos_API/change_log.txt) обновлён и содержит полную детализацию изменений;
  • версия и дата верхнего блока в публичном и внутреннем логах совпадают между собой и с Regos_API/Regos_API.csproj;
  • при изменениях миграций БД (db_updates) запись о миграции добавлена в changelog;
  • фиксируемые лимиты и значения по умолчанию совпадают с кодом, а конфигурируемые параметры помечены как «задаются серверными настройками»;
  • примеры JSON валидны;
  • текст без опечаток и копипаст-ошибок;
  • lastmod обновлён.

9. Ответственность

  • Автор изменения в коде отвечает за синхронное обновление документации.
  • Ревьюер проверяет соответствие документации фактическому поведению API.
  • При споре приоритет у исполняемого кода и тестируемого поведения.