💚 OpenAPI (Swagger) - практические руководства по документированию REST API через код 💚

Чтобы работать с Backend (REST API), важно понимать, что такое OpenAPI и зачем нужен Swagger.


👉 OpenAPI — это стандарт описания REST API в формате .yaml или .json.

Это не только документация «для людей», это машиночитаемая спецификация, на основе которой можно:

✅ генерировать и валидировать код (или наоборот собирать её из кода)
✅ писать автотесты
✅ создавать мок-сервера
✅ и оформлять API-документацию



👉 Swagger — набор инструментов для работы с OpenAPI:
– Swagger Editor — редактор .yaml файлов OpenAPI
– Swagger UI — интерфейс с кнопками и примерами
– SwaggerHub — облако, где можно делиться документацией (и делать портфолио)
– Codegen — генератор серверов и клиентов

Дополнительные инструменты для работы с OpenAPI:
🛠 Insomnia
🛠 Postman



👉 Что входит в идеальную API-документацию в формате OpenAPI, которую можно положить в портфолио СА:

1️⃣ Общее описание проекта
2️⃣ Настроенная авторизация
3️⃣ Выбор окружения (mock, dev, prod)
4️⃣ Описания у каждого метода
5️⃣ Примеры всех ответов: успех и ошибки
6️⃣ Реалистичные JSON-примеры
7️⃣ Настроенные Headers
8️⃣ В инструкциях и примерах ниже — по 2 метода. Для портфолио нужно хотя бы 10 👍



📍Спецификация OpenAPI может генерироваться из кода, автоматически, но часто бывают ситуации, когда её надо описывать аналитикам вручную, на этапе проектирования методов с нуля.


Чтобы разобраться с OpenAPI предлагаю вам серию практических руководств 👇

👉 Проект по онлайн-библиотеке:
🔗 1. Регистрация аккаунта и создание демо-проекта
🔗 2. Создание собственного проекта и работа с базовыми настройками, первые строки кода
🔗 3. Описание методов POST и GET по спецификации OpenAPI

👉 Проект по онлайн-календарю — управление мероприятиями:
🔗 часть 1
🔗 часть 2
🔗 часть 3

👉 Готовая OpenAPI спецификация для проекта #VetCareGA:
https://app.swaggerhub.com/apis/getanalystinternatio/VetCareGA-GetAnalyst/1.0.0
(для РФ - открывать с VPN, чтобы не было ошибки "нет доступа")

👉 Официальный образец кода OpenAPI - PetStore:
https://editor.swagger.io/


Умение работать с OpenAPI помогает структурировать понимание REST API.

А ещё это отличный способ показать свои навыки проектирования API через портфолио 📂


#RestApiGA

📱 GetAnalyst | 💙 VK | 💬 Max