В этом квартале моя команда разрабатывает новый веб-сервис, и я вызвался защищать его дизайн. Ну наконец то! Возможность увидеть, как развивается движение API-first!

Прелюдия

Мой первоначальный опыт работы с OpenAPI оставил у меня смешанные чувства. Я использовал его в нескольких проектах, но обычно как задним числом. Код для сервера и конечных точек уже был там, я просто аннотировал конечные точки, чтобы сгенерировать спецификацию OpenAPI для приятного пользовательского интерфейса API и возможности генерировать клиентов. Это было красиво, но некоторые из них были немного не в восторге. Моя основная претензия: генерировать клиентов было довольно неприятно.

Во-первых, нужно найти генератор, который использует библиотеки и языки, соответствующие стеку технологий вашей компании. Вариантов много, но иногда не совсем подходит. Например, я использую Java и знаком с Retrofit для вызовов API и Jackson для сериализации/десериализации, но эта комбинация недоступна. Доступна модернизация с помощью GSON, и все остальное с Джексоном доступно, но не оба вместе. Я думал, что было бы легко просто создать свой собственный шаблон, но кривая обучения казалась высокой, и я еще не был готов погрузиться в нее. Не конец света, но не идеал.

Затем, когда вы выбрали генератор клиентов, будьте осторожны; если спецификация изменится, клиенты должны быть созданы заново. Таким образом, даже если вы можете изменить сгенерированный код, вы можете этого не захотеть, потому что следующая регенерация кода перезапишет ваши изменения. Вероятно, есть способы слияния поколений, чтобы внести изменения, но я просто хотел, чтобы это было более прямолинейно. Не говоря уже о том, что просто неудобно говорить своим товарищам по команде в обзорах кода: «Да, просто игнорируйте этот код, он просто генерируется, и я не собираюсь его менять».

Все это, чтобы сказать, вещи чувствовали себя немного неотшлифованными.

Теперь я возвращаюсь через несколько месяцев, чтобы снова ориентироваться в пространстве. Я надеюсь получить какой-то рабочий процесс, который позволил бы мне обсудить дизайн с моими товарищами по команде и легко преобразовать его в спецификацию OpenAPI, которая затем легко генерирует каркас для нашего проекта, который затем легко позволяет нам добавить нашу бизнес-логику, которая затем легко доставляет нас к производству. Легко, верно?

Пока не совсем. Не нужно долго пролистывать инструменты OpenAPI, чтобы понять, что существует множество вариантов и не так много указаний, какой из них подходит именно вам. Именно в этот момент я понял, что может понадобиться руководство: возможно, журнал кого-то, блуждающего в мире OpenAPI, даже этот самый блог.

Начиная

Для начала я просто хотел бы настроить хорошую среду разработки. С редакторами я человек простого вкуса. Мне нравятся такие вещи, как подсказки кода и привязки клавиш vim. Может быть, сделать его бесплатным. Редактор Swagger, вероятно, достаточно близок для большинства людей, но в глубине души я просто хочу, чтобы для него был пакет emacs. Я ищу золотую середину… Похоже, есть многообещающий плагин для VSCode. Давайте попробуем.

VSCode OpenAPI

Прочитав документацию о том, как сгенерировать новую спецификацию OpenAPI, я не мог в этом разобраться, поэтому я перешел к примеру Petstore редактора Swagger, преобразовал его в OpenAPI3, преобразовал в YAML и скопировал. После небольшого исследования он чувствует себя довольно хорошо.

  • ✅ Подсказка кода
  • ✅ Привязки клавиш Vim
  • ✅ Бесплатно

Swagger-UI

Было бы неплохо, если бы у меня был предварительный просмотр swagger-ui во время редактирования, верно? После небольшого поиска я обнаружил, что есть образ докера, который должен сделать все это за вас. Кроме того, если вы подключите локальный каталог к ​​контейнеру докеров, вы сможете обновить спецификацию и обновить страницу без повторного развертывания образа.

Вот текущее содержимое моего файла docker-compose:

version: "3.7"
services:
  swagger-ui:
    image: swaggerapi/swagger-ui:latest
    ports:
      - "80:8080"
    volumes: 
      - ./:/openapi-spec
    environment: 
      - SWAGGER_JSON=/openapi-spec/openapi.yaml

Предполагая, что у вас уже настроен докер, вы сможете запустить его с помощью следующей команды:

$ docker-compose up
  • ✅ Предварительный просмотр пользовательского интерфейса Swagger

Что ж, похоже, это будет довольно удобная среда разработки для меня. Я использую редактор, в котором есть то, что мне нужно, и у меня есть возможность легко визуализировать, как мои изменения влияют на интерфейс Swagger. Было бы неплохо, если бы страница Swagger-UI автоматически обновлялась, но это можно сделать с помощью расширения для браузера. Так что, думаю, я чувствую себя здесь довольно хорошо.

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