Рубрики
Uncategorized

Зачем документировать API для отдыха в качестве кода?

TL; DR, если вы уже знакомы с Openapi и его местом в приложении Life-Cycle, … Помечено с AWS, Serverless, DevOps, Nowners.

Если вы уже знакомы с Openapi и его местом в приложении Life-Cycle, перейдите к главе «Инструментарива», которая является ядром этого блога.

Оставайтесь настроиться на следующую статью. Я обсужу реализацию с помощью Openapi, а также поддержка Terraform.

Спасибо за чтение!

  • TL; доктор
  • Тема разрыва
  • Зачем документировать API для отдыха в качестве кода?
  • Что такое operapi?
  • Где Openapi вписывается?
    • Требования, анализ и дизайн
    • Код и тест
    • Производство и техническое обслуживание
  • Инструменты?
    • Дизайн и развитие
    • Рамки внедрения
    • Генерация кода
    • Валидация и тестирование
  • Что дальше?
  • дальнейшее чтение

Есть много способов создавать в эти дни API, через использование таких структур, как Экспресс (Узел окружающей среды), Java Spring или облачные собственные решения, такие как API Gateway От Amazon Web Services.

Всеобъемлющая проблема, с которой я вижу с использованием этих решений исключительно это то, что они не описывают «API как код» Отказ Вы можете удивиться, почему мне все равно? Вот несколько причин, почему:

  • Способность генерировать сервер и клиент Боковой код от языка программирования Agnostic Rest API файла определения API (Openapi).
  • Как Инструмент связи , это основу документации, которая читается как интерфейс, бизнес, третьими лицами (Public API), так и в задневских разработчиках.
  • Следует за Инфраструктура как код парадигмы , мы можем проверить и подтвердить наши определения API для отдыха (конечная точка, модели, безопасность и ввод и выход). Мы можем Версия для управления Наши определения API.
  • Окружающая среда разработки , легко генерировать заглушки для отдыха API и имеют программу разработчиков передней/задней стороны против спецификации.
  • Поддерживает формальный Спецификация объекта модели (например. JSON SCHEMA ), который указывает входы и выходы конечных точек API.
  • Сохраняет вашу реализацию и формальный спецификационный документ API в синхронизации Отказ Редко редко, что документация продолжает синхронизировать с реальной мирной ситуацией. Мы обычно забываем обновить нашу документацию на протяжении всех изменений.

Сказав это, как Openapi предлагает это решить?

Хорошие практики дизайна и программирования рекомендуют использовать Определения интерфейса Отказ Определение интерфейса определяет, какая система или кусок кода (модуль и т. Д.) выполняют с точки зрения высокого уровня, а затем вы программируете на этот интерфейс.

Это достигает развязки фактического кода реализации из кода интерфейса (внешний мир в широком смысле). Мы свободны выбрать, как мы реализуемся против договора до тех пор, пока мы его удовлетворены. Кроме того, мы упрощаем дизайн приложений путем абстрагирования как можно больше информации о реализации, как мы можем ( Принцип Black Box ).

Openapi имеет именно то, что он предоставляет определение интерфейса, которое модифицирует приложение перед передним лицом и в задней панели «обработка/хранилище данных» часть приложения (типичная трехстрадающая архитектура).

Как это произошло через документ спецификации API отдыха, который определяет в конечных точках кода (YAML или JSON) API и моделями данных ( JSON Schema ) среди прочего. Благодаря этому файлу определения определения языка программирования Agnostic API вы можете генерировать код на ярусах приложений (передний и задний конец) и проверять ввод и вывод против его определения схемы JSON.

Поэтому хороший и хорошо документированный дизайн этого интерфейса принесет пользу всему жизненному циклу развития приложений.

Есть несколько шагов, участвующих в том, чтобы получить все это работать вместе. То, что мы будем закрывать вкратце:

  • Где Openapi 3 вписывается в ваш процесс разработки?
  • Какую инструменты доступны?
  • И, наконец, следующие шаги Я буду покрывать более поздние сообщения в блоге

Я еще не буду охватывать структуру языка в глубине языка, я сделаю это в более поздних постах в блоге с примером приложения. На данный момент обзор Это Краткое объяснение, чтобы получить идею.

В целом мы можем определить эти Фазы развития приложений, и я надену несколько вместе, чтобы консинсировать обсуждение:

  • Требования, анализ и дизайн; Что мы строим?
  • Код и тест Мы строим здание и тестирование.
  • Производство и обслуживание , Это в производстве и бега

Здесь мы можем иметь несколько итераций фаз в зависимости от стиля управления проектами (Agile, водопад и т. Д.) Опять же, очень широкая тема. На данный момент давайте рассмотрим эти фазы, где Openapi вписывается?

Требования, анализ и дизайн

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

Расширения (например, CloudPoints Google CloudPoints Google Cloud , AWS API Gateway ) позволяют поставщикам или компаниям добавлять «функции» в спецификацию API. Например, AWS API Gateway разработал расширения для кодификации его интеграции с сервисами Backend. Это означает конечную точку, например Получить/клиент/2 , можно напрямую интегрировать с базой данных DynamOdb через шаблон скорости. Или, с выполнением выполнения кода, такими как Лямбда Отказ

Все это формализировано в документ, который удовлетворяет как то почему, так и как API. Который приводит нас к следующим шагам, коду и тесту.

Код и тест

На этом этапе обычно тестер будет иметь документ, который описывает тестовые случаи в отношении сторон деловых требований, но ему придется ждать, чтобы сделать любой Тестирование контракта Прежде чем API доступен для этого. С помощью документа Openapi вы получаете начало головы, тесты могут быть созданы из спецификации (до определенной точки).

На стороне разработчика API уже может быть сгенерирован как клиент и Server Side заглушка из документа Openapi. Это облегчает разработку независимого клиента и сервера.

Разработчики и тестеры могут итеративно работать через тестирование и развитие контрактов в гораздо более быстрых темпах, чем раньше. Кроме того, оба клиент и Сервер Сторона может использовать валидацию моделей данных благодаря использованию определения схемы JSON.

Производство и техническое обслуживание

Как только приложение попадет в Производство и обслуживание Фаза Спецификация эффективна для:

  • Проверка Здесь мы проверяем Спецификационный документ Openapi такой же, как то, что развернуто. Оснащено такими как ДРЕДД может помочь здесь
  • Тестирование То, что мы намерены развернуть до производства, работает ли он в соответствии с спецификацией?

  • Документация отвечать на такие вопросы как;

    • Что было построено,
    • Как разработчики могут быть разработчики, внутренне и потенциально внешне, реализуют против спецификации API.

Теперь мы добираемся до мяса и костей Openapi и почему я люблю использовать его, инструментарий!

Это может занять несколько тысяч строк кода, чтобы указать каждую вещь о вашем API, но затем автоматизация, которую вы развязали, делает этот усилитель производительности, которую вы не поверите.

Так что давайте посмотрим, пожалуйста, мы.

Дизайн и развитие

  • Swagger Hub и Swagger Editor , Swagger в целом (как создатели Swagger/openapi) предоставляют инструменты на применении жизненного цикла. Я особенно любил их редактор, чтобы подтвердить спецификацию на лету, а как инструмент генерации документации/кода.

  • Визуальный студийный код Отказ В этом редакторе есть много плагинов, которые упрощают редактирование больших документов Openapi, плагины, которые я использую:

Рамки внедрения

Несколько основных рамок, а также облачных собственных решений, которые я использовал:

  • AWS API Gateway , вы можете использовать IAC Tooling или GUI, чтобы импортировать документ Swagger/OpenAPI, и он автоматически создаст конечных точек. Есть специфические AWS Распространения Спецификация Openapi, которая добавит аутентификацию, а Интеграция с aws lambda например.
  • Java Spring Boot/Maven Integration , Это Статья описывает возможную интеграцию между двумя.
  • Узел/экспресс
    • Openapi Enforcer Имеет определенный боковой проект, который автоматически генерирует конечную точку в вашем приложении Express. Он также включал проверку данных через определения схемы JSON в документе OpenAPI, см. Валидация подраздел.

Генерация кода

Оба из них обеспечивают аналогичный набор вывода генератора клиента и сервера

Клиенты API ActionScript, ADA, APEX, Bash, C, C # (.NET 2.0, 3.5 или более поздней версии .NET Стандарт 1.3 — 2.0, .NET CORE 2.0), C ++ (CPP-RESTSDK, QT5, TIZEN), CLOJURE, DART (1.x, 2.x), Elixir, Elm, Eiffel, Erlang, Go, Groovy, Haskell (HTTP-Client, Servant), Java (Jersey1.x, Jersey2.x, OKHTTP, RetoFit1.x, RetoFit2.x, Figitor, Restemplate, RESTARESY, VERTX, Клиентская библиотека Google API для Java, Budd-Bucted, Tpen 5 Web Client, MicroProfile Clients), Kotlin, Lua, nim, node.js / javaScript (es5, eS6, angularjs с компиляторы Google compilure аннотации, типы потоков), objective-c, ocaml, perl, php, powershell, python, r, ruby, rust (rust, rust-server ), Scala (Akka, http4s, Scalaz, Swagger-Async-httpClient), Swift (2.x, 3.x, 4.x, 5x), Teamscript (Angularjs, Angular (2.x — 8x) , Aurelia, Axios, Fetch, Inversify, jQuery, Node, RXJS)
Сервер заглушки ADA, C # (CORE ASP.NET CORE, NANCESFX), C ++ (Pistache, Rested, QT5 QHTPHENCINE), ERLANG, F # (GIRAFFE), GO (NET / HTTP, GIN), HASKELL (Servant), Java (MSF4J, Sprage, Ondertow , JAX-RS: CDI, CXF, Increlent, Джерси, RESTAWY, PLAY Framework, PKMST, VERT.X), Kotlin (Spring Boot, Ktor, Vertx), PHP (Laravel, Lumen, Slim, Silex, Symfony, Zend repressive) , Python (колба), Nodejs, Ruby (Sinatra, Rails5), Rust (Rust-Server), Scala (Finch, Lagom, Play, Scalatra)
  • CWAGGER CODEGEN и Github Поддерживает меньшие языки и рамки, но могут точно соответствовать вашим потребностям.
Клиенты API ActionScript, Ada, Apex, Bash, C # (.NET 2.0, 3.5 или более поздней версии), C ++ (CPPREST, QT5, TIZEN), Clojure, Dart, Elixir, Elm, Eiffel, Erlang, Go, Groovy, Haskell (HTTP-клиент, Слуга), Java (Jersey1.x, Jersey2.x, OKHTTP, RetoFit1.x, RetoFit2.x, Figapit, Resttemplate, Resteasy, Vertx, Google API Клиентская библиотека для Java, Budd-Bucted), Kotlin, Lua, Node.js (ES5, ES6, Angularjs с аннотациями компилятора Google Complue) Objective-C, Perl, PHP, PowerShell, Python, R, Ruby, Rust (Rust, Rust-Server), Scala (Akka, http4s, swagger-async-httpClient), Swift (2.x, 3.x, 4. x, 5x), Teadercript (Angular1.x, Angular2.x, Fetch, jQuery, Node)
Сервер заглушки ADA, C # (CORE ASP.NET CORE, NANCESFX), C ++ (Pistache, Restbed), Erlang, Go, Haskell (Servant), Java (MSF4J, Spring, Ondertow, Jax-RS: CDI, CXF, Increlent, Resteasy, Play Framework , Pkmst), Котлин, PHP (люмен, тонкий, Silex, Symfony, Zend repressive), Python (колба), Nodejs, Ruby (Sinatra, Rails5), Rust (Rust-Server), Scala (Finch, Lagom, Scalatra)

Валидация и тестирование

  • ДРЕДД Является ли библиотека инструмента CLI/JavaScript, которая может подтвердить вашу спецификацию на работе с запущенным сервером. Поддержка Openapi 3 все еще экспериментальная (!)
  • Openapi Enforcer Библиотека валидации для сервера бокового узла (опционально экспресс).
  • Swagger Test Generation Автоматически создает тестовые случаи для определенных кодов состояния HTTP, и он также может сделать тестирование нагрузки.
  • Валидаторы схемы JSON/Генераторы/тестирование Существует множество инструментов для проверки, генерирования и теста на основе JSON Schemas.

На следующей неделе я продемонстрирую с Террафом и AWS API Gateway, как мы можем использовать спецификацию Openapi для создания API на стороне сервера с проверкой.

Дайте мне знать в комментариях ниже, если эта статья была полезна для вас и что еще вы хотели бы прочитать о.

Если вы уже используете Openapi, пожалуйста, сообщите мне в комментариях, на что с ним опыт работы.

Спасибо за чтение и до следующей недели!

Оригинал: «https://dev.to/rolfstreefkerk/why-document-a-rest-api-as-code-5e7p»

Читайте ещё по теме: