Нарушение хотя бы одного правила ведет к росту запросов в поддержку на 25% и снижению adoption rate API.
1. Структура по OpenAPI 3.1
Используйте стандарт OpenAPI для описания эндпоинтов, параметров и схем ответов. Обязательно включайте теги `summary`, `description`, `operationId` для автоматической генерации документации (через Swagger UI или Redoc).
2. Четкое версионирование
Указывайте версию API в URL (`/v1/resource`) или заголовке `Accept: application/vnd.company.v1+json`. Запрещено изменять поведение без обновления версии.
3. Примеры «из коробки»
Для каждого метода предоставьте:
- запрос с заголовками и телом (в формате cURL, Postman, JavaScript).
- успешный ответ (200 OK) и пример ошибки (400 Bad Request).
- комментарии к неочевидным параметрам (например, `?limit=100` — максимальное значение 200).
4. Описание ошибок в формате RFC 7807
Стандартизируйте коды ошибок:
```json
{
"type": "https://errors.company.com/invalid-param",
"title": "Некорректный параметр",
"detail": "Поле 'email' не соответствует формату",
"status": 400
}
```
5. Аутентификация в одном месте
Опишите способы авторизации (OAuth 2.0, API keys) в разделе «Authentication». Укажите:
- как получить токен.
- пример запроса с заголовком `Authorization: Bearer <token>`.
- срок действия токена.
6. Активный залог и краткость
Пишите: «Метод создает новый ресурс», а не «Новый ресурс создается методом» (максимальная длина описания — 2 предложения).
7. Интерактивные пробники
Интегрируйте в документацию инструменты вроде Postman или Swagger UI для тестирования запросов прямо в браузере (добавьте кнопку «Попробовать сейчас»).
8. Соответствие GDPR и безопасности
В разделе «Приватность» укажите:
- какие данные обрабатываются.
- методы шифрования (TLS 1.3+).
- срок хранения логов (макс. 30 дней).
9. Локализация терминов
Для многоязычных API:
- используйте i18n-метки (например, `error_invalid_email` вместо текста).
- добавляйте языковые параметры в запрос (`?lang=ru`).
- запрещено смешивать языки в одном документе.
10. Обратная связь и живые обновления
- размещайте кнопку «Нашли ошибку? Исправьте это» с ссылкой на GitHub-репозиторий.
- автоматически обновляйте документацию при изменениях в коде (через CI/CD-пайплайны).
- добавляйте дату последнего обновления: «Актуально на 19.11.2025».
Почему это важно в 2025 г.:
- AI-интеграция: инструменты вроде GitHub Copilot считывают OpenAPI-спецификации для генерации клиентского кода.
- Доступность: требования WCAG 2.2 обязывают добавлять альтернативные тексты для схем и примеров.
- Скорость внедрения: четкая документация сокращает onboarding новых разработчиков на 40% (данные Gartner, 2025).