предисловие
В настоящее время на рынке существует множество платформ управления API.Когда таких платформ много, команде разработчиков нужно тратить больше времени на анализ и сравнение при выборе.Как выбрать инструмент управления API, который подходит вашей команде, очень важно , потому что это очень важно, в значительной степени определяет способ сотрудничества между командами.
Зачем вам нужно управление API
Традиционным способом управления API является использование текстовых документов. Недостатком этого метода является то, что его сложно поддерживать и управлять, и в то же время легко вызвать рассинхронизацию. Со временем документы API разбросаны по различных местах, что приводит к несогласованным форматам данных интерфейса и частым интерфейсам. Сообщите об ошибке, которая вызовет конфликты между командами.недоверие,Так что документ API постепенно отбрасывается; Как только это произойдет, разработчики часто будут определять различные детали интерфейса API посредством запросов, общения, совместной отладки и проверки кода.Командам легче уклоняться от ответственности друг от друга, а затраты на разработку постепенно возрастают.
Интересно, что такого рода проблемы нельзя решить, набросив на команду разработчиков сверхфункциональную платформу управления API. Это требует использования соответствующих стратегий управления.
что нам действительно нужно
С точки зрения ориентированности на результат, если вы стоите в интерфейсе APIпотребительская перспектива, то необходимая нам API-документация должна обладать следующими важными характеристиками:
- Описание уместно
- Разумное разделение
- Синхронизация по времени
- Прошел тест
- легко использовать
В настоящее время мы обнаружим, что эти вещи в основном делаются людьми, а платформа и инструменты просто обеспечивают более привлекательный интерфейс и более удобные инструменты, помогающие нам быстрее достичь пунктов 3 и 4. Только тогда мы поняли,Управление API сосредоточено на людях, а не на инструментах.
как управлять
Кто производит, кто отвечает за управление.Чтобы сделать эту идею более приемлемой, ее нужно превратить в привычку, поэтому лучше всего сочетать ее с лучшими навыками другого человека, добавить соответствующие ограничения и дать этому человеку определенные права.
- Инструменты лучше всего сочетаются с кодом (привыкание).
- Пройти испытание (ограничение).
- Иметь право определять некоторые интерфейсы (предоставлять определенные права).
Анализ платформы
онлайн-продукт
Существует множество таких продуктов, которые в основном можно разделить на бесплатные и платные, а некоторые продукты предоставляют больше дополнительных услуг, таких как мониторинг, автоматизированное тестирование и т. д.
Преимущество
- Не требует обслуживания сервера
- Предоставляет функции совместной работы в команде
- Обеспечить онлайн-тест интерфейса
- Уведомление об изменении интерфейса (не обязательно)
- Управление несколькими проектами
недостаток
- Платформа может прекратить техническое обслуживание в любое время
- Интерфейсы нуждаются в ручной синхронизации
- Форматы интерфейсов основных платформ неоднородны, и миграция представляет собой проблему.
- Контракт интерфейса не гарантируется (проходит ли он тест? Правильно ли он сформирован?)
Интеграция с фреймворком
Интеграция фреймворка относится к интеграции фреймворка автоматической генерации документов API в среду разработки.В настоящее время на основе spring в основном springfox-swagger2 и spring rest doc.
Springfox-Swagger2
недостаток
- Инвазивный
- Добавьте небольшую стоимость обучения
Преимущество
- Безопасная определяемая аутентификация доступа к интерфейсу
- Код — это документация
- Красивый интерфейс
- предоставить тест
- Сообщество обеспечивает интеграцию с Spring-Boot
Spring REST Doc
Позиционирование продукта заключается в документации API, основанной на тестировании, обеспечивающей сочетание рукописной документации и автоматического создания, автоматического создания документации на основе тестирования API и создания документации API только после прохождения теста, поэтому точность документации может быть гарантирована. .
недостаток
- Добавьте небольшую стоимость обучения
- Документация требует небольшой ручной настройки, но, к счастью, настройка относительно проста.
- Выполнение тестов API перед публикацией интерфейса занимает некоторое время.
Преимущество
- Безопасный, выбираемый объем обмена документами
- неинвазивный
- Контракт интерфейса (автономная html-документация API может быть создана только после прохождения теста API)
- Код — это документация
- весенняя экология, легко интегрируется
самодельный
Когда интеграция фреймворка и общедоступная сетевая онлайн-платформа не могут удовлетворить потребности, вы можете создать собственную платформу управления API. В настоящее время в этой области существует множество инструментов с открытым исходным кодом, и наиболее часто используемые из них перечислены на интеллект-карте.
Преимущество
- управляемый
- настраиваемый
недостаток
- Требуется обслуживание сервера
- Интерфейсы нуждаются в ручной синхронизации
- Контракт интерфейса не гарантируется (проходит ли он тест? Правильно ли он сформирован?)
Суммировать
В статье изложены мои собственные взгляды на управление API, а также дан краткий анализ некоторых инструментов API, представленных на рынке, а также обобщены преимущества и недостатки различных продуктов. Цель управления API — облегчить совместную работу команды. Основываясь на этом понимании выше, я действительно обнаружил, что Spring REST Doc подходит лучше всего.