# HTTP API Documentation Writing

> Проектирование, создание, адаптация и ревью аналитической Markdown-документации HTTP API: публичных и приватных областей, версий, ресурсов, endpoint-ов, параметров, заголовков, моделей запросов и ответов, пагинации, фильтрации, сортировки, перечислений, ошибок, примеров, стабильных обозначений и SUMMARY.md. Использовать, когда HTTP-контракт должен быть достаточен для реализации без новых продуктовых решений. Не использовать для определения application/domain-контрактов, реализации FastAPI, входящих сообщений, фоновых процессов или восстановления требований из кода без разрешения.

- Skill: `nemagu/http-api-documentation-writing` (Agent Skill, multi-file: 5 files)
- Install (CLI): `npx skillmds@latest add nemagu/http-api-documentation-writing`
- Raw SKILL.md: https://api.skillmd.com/api/skills/nemagu/http-api-documentation-writing/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: Nemagu (https://skillmd.com/u/nemagu)
- Updated: 2026-09-21
- Page: https://skillmd.com/skills/nemagu/http-api-documentation-writing

---


# Документирование HTTP API

Описывать наблюдаемый HTTP-контракт независимо от фреймворка и языка реализации.

## Обязательные справочники

Перед созданием или ревью читать:

- [structure.md](references/structure.md) — структура файлов и навигация;
- [endpoint-contract.md](references/endpoint-contract.md) — нормативное содержание
  endpoint-а и моделей;
- [review-checklist.md](references/review-checklist.md) — проверка готовности.

## Размещение и навигация

Размещать HTTP-документацию внутри `presentation/http/` принятой структуры.
Внутреннюю иерархию областей, версий, ресурсов, endpoint-ов и моделей определяет
этот скил. Не создавать отдельный корневой `external-contracts/http`.

Формировать только фрагмент `SUMMARY.md`, начинающийся с «HTTP API». Главный скил
встраивает его внутрь «Презентационного слоя»; HTTP-скил не переставляет корневые
архитектурные разделы.

## Архитектурная граница

### Стабильные обозначения

Использовать схему
`<контекст>.presentation.http.<область>.<версия>.<ресурсы>.<действие или модель>`.
Область, версия, ресурс и действие являются отдельными смысловыми сегментами; не
склеивать ресурс с действием и не пропускать ресурс. Одинаковый endpoint или
модель во всей документации имеет одно обозначение независимо от имени файла.

Presentation вызывает публичную application-операцию. HTTP-модели принадлежат
presentation и не являются командами, запросами или DTO application. Сопоставлять
только публичные application-исходы; не интерпретировать domain-ошибки напрямую.

Код не считать источником требований. При адаптации существующей документации
читать код только после отдельного разрешения пользователя и только для
разрешения названного расхождения.

## Рабочий процесс

1. Согласовать область доступности, версию, базовый адрес, аутентификацию,
   формат содержимого, общие ошибки и политику ответов команд.
2. Определить ресурсы и их границы.
3. Связать каждый endpoint с одной публичной application-операцией.
4. Описать каждый источник входа и отдельные HTTP-модели.
5. Описать поле за полем валидацию и преобразование в application-вход.
6. Описать успешный результат, заголовки и преобразование результата.
7. Сослаться на общие ошибки и зафиксировать только отклонения endpoint-а.
8. Определить повтор, совместимость и стабильное обозначение.
9. Добавить минимальные примеры, не расширяющие нормативные таблицы.
10. Обновить навигацию и выполнить checklist.

До массового описания однотипных ресурсов полностью проработать один эталонный
ресурс и согласовать его с пользователем.

## Согласование решений

Не выбирать самостоятельно метод, адрес, статус создания, `Location`, каноничный
завершающий `/`, правила `null`, неизвестных полей, сортировки или совместимости.
Предлагать варианты и фиксировать выбранное решение глобально, если оно общее.

За один подход задавать до пяти коротких, до трёх средних либо один-два крупных
связанных вопроса. Не повторять глобальные вопросы для каждого ресурса.

## Политика минимальных ответов

Предлагать как согласуемый вариант:

- `GET` возвращает запрошенные данные;
- создание возвращает только идентификатор созданного агрегата;
- изменение, удаление и восстановление возвращают `204 No Content`;
- актуальное состояние клиент получает отдельным `GET`.

Статус создания и заголовок `Location` согласовывать отдельно. Не считать их
автоматическим следствием этой политики.

## Готовность

Документ готов, если реализация не требует выбирать адресацию, источник или
представление значения, обязательность, `null` и пустое значение, валидацию,
преобразование, сортировку, пагинацию, статусы, заголовки, тело, повтор или
совместимость.

Каждый содержательный документ завершать разделом `## Открытые вопросы`. Если
вопросов нет, писать `Открытых вопросов нет.`. Не писать это, пока сохраняется
неявно выбранное решение.