Простой ликбез почему Swagger ≠ OpenAPI
У нас в команде всё, что касается документации REST API, по привычке называют «сваггер» (догадайтесь, кто виноват? 🙈).
А между тем Swagger один из инструментов, а не сама документация. Поэтому сейчас переучиваемся.
И так как виновата я, то взяла ответственность на себя и подготовила памятку для коллег с разъяснениями. Делюсь и с вами.
📌 Спецификация OpenAPI (OAS) 📌
конкретный YAML/JSON-файл или набор таких файлов, описывающий ваш API. Это источник правды для документации и автогенерации кода.
Я люблю править спеку в VS Code с набором плагинов (если нужен список дайте знать). Но можно в любом YAML-редакторе. А если JSON/YAML пока пугает попробуйте Stoplight Studio.
📌 OpenAPI-документация 📌
красивое, человекочитаемое отображение спеки, которое может быть в Swagger, но не обязательно. Мне нравится ещё Redoc.
📌 Swagger UI 📌
инструмент для отображения в браузере или в Visual Studio. Легко читать, можно даже делать запросы, но менять к нем спеку нельзя.
Путь работы: Придумываем новые эндпоинты → Описываем их в спецификации OpenAPI → Пушим изменения в репозиторий → Ревью →
CI/CD подхватывает обновления, валидирует спеку → Собирает и разворачивает документацию в Swagger UI → С ней начинают работать бэки и фронты
Если вы всё ещё зовёте всё это “сваггером” — просто пересылайте этот пост коллегам
#Swagger #OpenAPI #СистемныйАнализ
У нас в команде всё, что касается документации REST API, по привычке называют «сваггер» (догадайтесь, кто виноват? 🙈).
А между тем Swagger один из инструментов, а не сама документация. Поэтому сейчас переучиваемся.
И так как виновата я, то взяла ответственность на себя и подготовила памятку для коллег с разъяснениями. Делюсь и с вами.
📌 Спецификация OpenAPI (OAS) 📌
конкретный YAML/JSON-файл или набор таких файлов, описывающий ваш API. Это источник правды для документации и автогенерации кода.
Я люблю править спеку в VS Code с набором плагинов (если нужен список дайте знать). Но можно в любом YAML-редакторе. А если JSON/YAML пока пугает попробуйте Stoplight Studio.
📌 OpenAPI-документация 📌
красивое, человекочитаемое отображение спеки, которое может быть в Swagger, но не обязательно. Мне нравится ещё Redoc.
📌 Swagger UI 📌
инструмент для отображения в браузере или в Visual Studio. Легко читать, можно даже делать запросы, но менять к нем спеку нельзя.
Путь работы: Придумываем новые эндпоинты → Описываем их в спецификации OpenAPI → Пушим изменения в репозиторий → Ревью →
CI/CD подхватывает обновления, валидирует спеку → Собирает и разворачивает документацию в Swagger UI → С ней начинают работать бэки и фронты
Если вы всё ещё зовёте всё это “сваггером” — просто пересылайте этот пост коллегам
#Swagger #OpenAPI #СистемныйАнализ