Разработка спецификации OpenAPI

1. Требования к архитектуре документации API:

1. Регламентация структуры и нумерации разделов: 1. Аутентификация, 1.1. API-ключи, 1.2. OAuth 2.0.

2. Содержать три типа контента:

• Справочники (Reference Guides);
• Учебные материалы (Tutorials);
• Примеры использования (Examples).

3. Семантическое версионирование API: в формате "MAJOR.MINOR.PATCH".

2. Организация файлов спецификации OpenAPI

1. Целесообразно выносить в отдельные файлы описания: методов, моделей, параметров и ошибок (ссылки на объекты путём указания путей до соответствующих файлов).
2. Использование скрипта для автогенерации шаблона спецификации OpenAPI позволяет заполнять метаинформацию.
3. Необходима постоянная актуализация спецификации.

3. Требования к документированию API:

1. Ясность - использование простого языка.
2. Полнота - указание: HTTP-методов, URL-структуры, параметров запроса (тип, обязательность, значения по умолчанию), структуры запросов и ответов, кодов ошибок с объяснением их причин и способов устранения (включая руководства по началу работы, примеры кода на нескольких популярных языках (JavaScript, Python, Java, C#) и информацию об управлении запросами).
3. Согласованность - регламентация правил именования ресурсов, стандартные методы, форматы данных и форматирование кода.
4. Практичность - пошаговые руководства для типовых задач и интерактивные элементы (консоли) для изменения параметров запроса с отображением результата в реальном времени.
5. Актуальность - ревью, тестирование и обновления с интеграцией документации в процессы разработки (DevOps/CI/CD).

4. Состав спецификации OpenAPI:

5. Ресурсы и методы

Объект path содержит доступные пути (конечные точки) и операции (методы) для API. Он состоит из:

1. Пути (конечной точки) — все пути в блоке path задаются относительно URL, определённых в блоке «Серверы», то есть полный URL запроса будет выглядеть так: <server-url>/path.
2. Операций (методов GET, POST и т. д.) включают:

• summary - название метода
• description - описание работы метода. Описывайте задачу, которую решает метод или свойство
• security: [] - определяет глобальный метод безопасности
• parameters - параметры запроса
• requestBody - тело запроса
• responses - описание ответа

Правила именования пути:

Методы:

6. Принцип обратной совместимости

1. Аддитивность - новые функции и изменения должны добавляться, а не заменять существующие (например, вместо того чтобы изменить тип поля `userId` с числового на строковый, лучше создать новый эндпоинт `/v2/users/{userId}).
2. Нарушающие изменения - применяются только в крайних случаях:

• удаление параметра или поля ответа;
• изменение типа данных, параметра или поля (например, из строки в число);
• изменение HTTP-метода;
• добавление обязательного параметра или изменение значения его по умолчанию;
• изменение структуры ответа (например, переход от простого типа к объекту или наоборот);
• изменение HTTP-кода ответа для определенного сценария.

3. Внедрение комплексной системы тестирования:

• проверка, что реализация соответствует спецификации OpenAPI/OAS (Dredd, Pact или oasdiff могут автоматизировать этот процесс);
• интеграционное тестирование - всех версий API на предмет совместимости с клиентскими SDK;
• регрессионное тестирование - проверка, что новые изменения не сломали уже существующую функциональность;
• отслеживание метрик ошибок, времени отклика и частоты запросов для обеих версий API сразу после выпуска.

4. Постепенное внедрение новых версий для снижения риска отказа.

5. Разработка и внедрение подробного Руководства по миграции.