Управление API является краеугольным камнем хорошего опыта API как для производителей, так и для потребителей. Мы много говорим о том, как OpenAPI — это гораздо больше, чем инструменты, но инструменты тоже могут очень помочь. Давайте посмотрим на доступные варианты и то, как они соответствуют вашему рабочему процессу.
Инструменты для управления API
Основным инструментом в инструментальном яжке API управление является Linter, иногда также называемый валидатором. Эти инструменты проверяют описание OpenAPI по набору стандартов. Какие стандарты? Те, которые вы настраиваете. Инвестирование времени для настройки Linter в поддержку согласованных стандартов API является ключевым компонентом для реализации хорошего управления API.
Есть несколько приличных инструментов, доступных для личинки, и большинство из них являются открытым исходным кодом, а это значит, что вы можете легко попробовать их и найти их. Попробуйте это для начала:
- Спектральный
- Вакуум
- Redocly Cli
Каждый из этих инструментов предложит «рекомендованный» набор правил по умолчанию. Тем не менее, они, как правило, довольно строгие, и я бы на самом деле не рекомендовал их в качестве отправной точки, если они тесно связаны со стандартами API, которые вы определили для себя. Особенно при модернизации управления API к существующему проекту API, медленный и итеративный подход является реальным рекомендуемым подходом.
Начните просто
Начните с выбора инструмента: в этих примерах я использую вакуум, но Spectral поддерживает ту же конфигурацию правила, если вы предпочитаете это. Отключите правила по умолчанию и включите, что имеет смысл для вашей ситуации. Отличное место для начала-включить правило OAS3-Schema и проверить, что у вас есть описание OpenAPI. Удивительно, сколько инструментов OpenAPI не совсем выводят действительный OpenAPI в любой ситуации.
Чтобы отключить правила по умолчанию и проверить действительное описание, используйте файл правил.
Запустите этот набор правил через ваш файл openapi.yaml с вакуумом, используя следующую команду:
Вакуумный простей -Details -Ruleset Rulesset.yaml openapi.yaml 1 вакуумный прост
Если у вас нет удобного файла OpenAPI, вы можете взять пример блога OpenAPI, который я использовал, и попробовать это. (Это включает в себя некоторые проблемы, которые будут выявлены, когда мы добавим еще несколько правил.)
Если описание OpenAPI является недействительным, проблемы и где в файле они будут отображаться в выводе. Команда также возвращает ошибку, поэтому этот инструмент полезен в настройке CI, где он вернет статус сбоя и предупредит вас о проблеме.
Выборочно добавить правила
Одна из причин, по которой рекомендуемые наборы правил являются такой проблемой для существующих API, заключается в том, что у них нет контекста того, что делает ваше приложение и что важно. Лучше сосредоточиться на областях, которые имеют значение для вашей организации, а не на общем наборе приоритетов.
В этом примере основное внимание уделяется опыту разработчиков, создавая API, с которым наши технические пользователи будут рады интегрировать. Чтобы поддержать это, первые правила, которые нужно добавить:
- Operation-operationId и операция-OperectionId-Unique Убедитесь, что каждая операция имеет уникальный идентификатор; Эти значения используются в качестве якоря в документации и часто в качестве имен методов в генерируемых SDK.
- ОПЕРУЖЕНИЕ ТАГА, ОПРЕДЕЛЕННЫЕ И ОПРЕДЕЛЕНИЕ ТЕГКИ ТРЕБУЕТСЯ каждый тег, используемый в описании API, который будет объявлен в разделе тегов верхнего уровня, и для получения описания.
- Операция по описанию, схемам и составной разработке гарантирует, что в описании API есть поля описания. Добавление значимой информации, написанная людьми, является низко висящим фруктом, когда дело доходит до улучшения опыта разработчика вашего API.
- Описание-дублирование предоставляет информационное сообщение низкого уровня, если два поля Описания идентичны, так как это обычно указывает на ошибку копирования/вставки.
С помощью дополнительных правил есть обновленный файл правил.
Вы можете заметить, что когда мы запускаем команду на этот раз, вывод сообщает о некоторых проблемах:
Выходные данные Vacuum сообщают об ошибках.
Ошибки вызваны одной из конечных точек, пропущенных как в операции (технически не требуемое поле в OpenAPI, но определенно хорошая идея) и описание. Попробуйте исправить ошибку самостоятельно и повторить команду, чтобы увидеть обновленный вывод.
Для ваших собственных описаний API выберите правила, которые соответствуют приоритетам, которые у вас есть. Покопайте документацию по наборам правил вакуума и создайте стартовый набор правил, соответствующих вашему собственному проекту.
Интегрируйте чеки в свой рабочий процесс
Прогулка API в нескольких точках жизненного цикла развития API является хорошей практикой, потому что он держит циклы обратной связи короткими и помогает разработчикам быстрее внедрять инновации.
Для проектов, первых, настраивание на локальных платформах разработки на локальных платформах является обязательным. Некоторые инструменты интегрируются в IDES, или вы можете запустить инструменты на CLI на своей машине разработки.
Независимо от того, разработаны или сгенерированы изменения OpenAPI, должны быть рассмотрены в запросе на притяжение, а проверки управления API, включая личинку, определенно принадлежат там! Используйте команду CLI сверху в существующей настройке рабочего процесса CI, такой как действия GitHub или трубопроводы Gitlab/Azure.
Vacuum может создать интерактивный отчет HTML, который является очень удобным способом просмотра вывода правил линии. Используйте его локально для более хорошего способа увидеть, что происходит, или создать его в процессе CI, чтобы дать рецензентам приятный интерфейс, на который можно посмотреть. Поддержка Vacuum для документации для каждого правила (включая любые пользовательские правила, которые вы создаете) — отличный способ предоставить больше контекста и советов для поддержки каждого правила.
Панельная панель Vacuum предоставляет интерактивные отчеты.
Возможно, вы также захотите посмотреть на команду приборной панели, которая создает панель мониторинга на основе терминала, или генерировать отчет в JSON или спектральном формате.
Управление API — это больше, чем автоматизация
Управление API — это больше, чем автоматизация, но автоматизация простых вещей действительно помогает. Не чувствуйте себя пугающими от длинных списков вещей, которые не идеальны или правила, которые не включены.
Добавление вкладки в вашу повседневную работу привносит качество и последовательность в разработку вашего API, и даже если есть вещи, которые вы не можете исправить сегодня, можно добавить чеки, чтобы избежать каких-либо регрессий или ошибок в новых функциях API по мере его роста.
Так что посмотрите, где вы находитесь с управлением API, и куда вы хотите пойти, и используйте подкладку, чтобы помочь вам сделать один или два шага по пути.
Hasura облегчает доступ к данным, мгновенно сочиняя API GraphQL, который поддерживается базами данных и услугами, чтобы команда разработчиков (или потребители API) стала немедленно продуктивной. Природа самого GraphQL и динамический подход Hasura облегчают интеграцию и итерацию. Узнайте больше последних из Hasura Trending Stories YouTube.com/thenewstack Tech Moving быстро, не пропустите эпизод. Подпишитесь на наш канал YouTube, чтобы транслировать все наши подкасты, интервью, демонстрации и многое другое. Группа подпишитесь с эскизом. Лорна Митчелл базируется в Йоркшире, Великобритания; Она является технологическим лидером и экспертом по опыту разработчиков, который увлечен API и инструментами разработчиков. Лорна служит в техническом руководящем комитете для спецификации OpenAPI, находится в совете … Подробнее от Лорны Митчелл
