Проектирование API (OpenAPI / Swagger)

Что это такое

Машиночитаемый документ со списком путей, методов на каждом из них, параметров, тел запросов и ответов и кодов состояния — так выглядит формат описания HTTP API. Он структурирован, а не написан прозой, поэтому один и тот же документ порождает документацию, клиентские библиотеки, заглушки сервера и тесты; OpenAPI — это формат, а Swagger — название семейства инструментов вокруг него.

Почему это важно

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

Что в этом треке

Написание спецификации (05-backend-data/09-api-design-openapi-swagger/01-writing-the-specification) — как описывать пути, схемы и ответы, чтобы документом можно было пользоваться.
Контрактное тестирование (05-backend-data/09-api-design-openapi-swagger/02-contract-testing) — как проверять, что реализация и описание всё ещё совпадают.

Предварительные требования

RESTful API (05-backend-data/06-restful-api)

Что читать дальше

RESTful API (05-backend-data/06-restful-api) — соглашения, которые описывает спецификация; начинайте с неё.
Аутентификация и авторизация (OAuth2 / JWT) (05-backend-data/10-authentication-authorization-oauth2-jwt) — схемы безопасности, которые спецификация объявляет для каждого эндпоинта.
CI/CD (06-cloud-devops/08-ci-cd) — где проверки контракта идут на каждое изменение.