Сначала спроектируйте или сначала запишите код, ваше дело

Мы представили спецификацию OpenAPI, редактор Swagger и пользовательский интерфейс Swagger. Давайте подробнее рассмотрим плагины Swagger Codegen и Swagger.

Swagger Codegen начинается со спецификации OpenAPI (OAS) и выполняет два действия:

  • Сгенерируйте заглушки сервера.
  • Создайте клиентские SDK.

В этой статье мы сосредоточимся на том, как создавать заглушки сервера. О том, как сгенерировать клиентские SDK, мы поговорим в другой статье.

Создание заглушек сервера - это первый подход к проектированию, который начинается со спецификации OpenAPI, определенных API-интерфейсов YAML или JSON для ресурсов, операций и моделей данных. После завершения проектирования бизнес-логика реализуется на основе сгенерированных заглушек сервера. Этот процесс дополнительно автоматизируется с помощью SwaggerHub, который представляет собой корпоративную версию инструмента Swagger. Здесь мы рассмотрим процесс создания вручную, чтобы понять более подробную информацию.

Существует также подход «сначала код», при котором сначала создается бизнес-логика. На основе существующей реализации API плагины Swagger генерируют спецификацию OpenAPI.

В общем, сообщество Swagger рекомендует подход сначала к дизайну. Подход «сначала код» принят организациями, в которых уже реализована существующая бизнес-логика.

Дизайн в первую очередь - Codegen для заглушек сервера

Давайте зайдем в редактор Swagger в Интернете: https://editor.swagger.io/. Скопируйте и вставьте следующее определение зоомагазина в формате YAML, официальный пример из спецификации OpenAPI 3.0, в редактор:

Щелкните меню Generate Server, и оно показывает множество вариантов серверов / фреймворков, таких как сервер Go, сервер Java, сервер Scala и сервер Node.

Выберите сервер, который поддерживает вашу внутреннюю реализацию. В этой статье мы используем nodejs-server в качестве примера. После щелчка nodejs-server в папке Downloads создается nodejs-server-server-generated.zip.

Откройте zip-файл и покажите этот проект Node / JavaScript в VSCode.

controllers/Pets.js - это код сервера, который обрабатывает createPets (строка 6), listPets (строка 16) и showPetById (строка 26).

Этот код контроллера является оболочкой для PetsService методов в service/PetsService.js.

Это сгенерированные Swagger серверные заглушки, которые реализованы не полностью.

Следуйте инструкциям в README, введите npm start в терминале:

$ npm start
> [email protected] prestart /Users/jenniferfu/nodejs-server-server-generated
> npm install
npm notice created a lockfile as package-lock.json. You should commit this file.
added 124 packages from 156 contributors and audited 124 packages in 4.125s
7 packages are looking for funding
  run `npm fund` for details
found 0 vulnerabilities
> [email protected] start /Users/jenniferfu/nodejs-server-server-generated
> node index.js
body-parser deprecated undefined extended: provide extended option node_modules/oas3-tools/dist/middleware/express.app.config.js:22:33
  Mock mode: disabled
Your server is listening on port 8080 (http://localhost:8080)
Swagger-ui is available on http://localhost:8080/docs

Перейдите к http://localhost:8080/docs, пользовательский интерфейс Swagger запущен и работает.

Однако выполните команду GET /pets, и мы получим ответ 404 Not Found.

Команда npm start вызывает node index.js, который создается из меню Swagger:

Строка 7 определяет порт сервера как 8080.

Строки 10–14 настраивают маршрутизацию в папку controllers, где Pet.js обертывают PetsService методы.

Строка 16 читает файл YAML.

Строка 20 запускает сервер на порту 8080, а пользовательский интерфейс Swagger доступен на http://localhost:8080/docs.

По-видимому, нет целевого хоста для обработки API в http://petstore.swagger.io/v1, указанном в api/openapi.yaml.

Чтобы выполнить команду пользовательского интерфейса Swagger, ему нужен действующий сервер / развертывание, которое прослушивает запросы и обслуживает ответы.

Либо нам нужно настроить сервер на http://petstore.swagger.io, либо мы можем выбрать лучшую альтернативу, предоставленную Swagger Codegen.

Сгенерированный код сервера устанавливает сервер на http://localhost:8080. Это можно проверить, позвонив GET /pets.

Все, что нам нужно сделать, это изменить api/openapi.yaml, чтобы URL-адрес сервера указывал на http://localhost:8080/v1.

Выполните команду GET /pets еще раз, и мы получим правильный ответ.

Фактически, мы можем избежать жесткого кодирования доменного имени. Просто сделайте так, чтобы URL-адрес сервера указывал на /v1.

Этот пример доступен в репозитории сервера.

Это упрощенный пример. В реальном проекте PetsService требует полномасштабного внедрения.

Code First - плагины Swagger

Мы видели, что в ряде проектов используется подход, основанный на коде. Если бизнес-логика уже реализована, кажется естественным использовать подключаемый модуль Swagger для создания спецификации OpenAPI.

Спецификация OpenAPI помогает создавать заглушки сервера, так зачем нам это нужно после того, как логика сервера будет реализована?

Что ж, пользовательский интерфейс Swagger - это хорошо документированный способ доставки API-интерфейсов разработчикам пользовательского интерфейса или другим потребителям. Спецификация OpenAPI также позволяет нам использовать Codegen для создания клиентских SDK, которые вызываются на стороне клиента, например приложения React.

swagger-maven-plugin Кун Чена хорошо известен. Этот плагин позволяет проекту с аннотациями Swagger генерировать спецификации Swagger, а также настраиваемые шаблонные статические документы на этапе сборки maven.

OpenAPI swagger-maven-plugin вдохновлен плагином swagger-maven-maven Конг Чена. Он использует библиотеку Swagger Core для создания документации OpenAPI из службы REST на основе JAX-RS с минимально возможными изменениями.

Нам лично нравится play-swagger, библиотека, которая генерирует спецификации Swagger из файлов маршрутов и отражения класса case, без аннотации кода. Хотя он определяется для каждого отдельного файла маршрута, определение аналогично спецификации OpenAPI, децентрализовано.

play-swagger записывает определение API в файлы маршрутов Scala Play в виде комментариев. Вот официальный пример о POST /users/:profileId/contexts/:contextName/cards.

Строки 1–10 - это спецификация OpenAPI, за исключением символов комментариев.

Строка 11 показывает маршрут команды POST, обслуживаемой controllers.api.Cards.createCard.

Схема CardCreated определяется следующими классами case.

Результирующая спецификация Swagger выглядит так.

Подход «сначала код» - это более традиционный способ создания API. Сначала реализуйте API, а затем сгенерируйте документацию Swagger из кода.

Заключение

OpenAPI определяет общий язык для веб-служб RESTful. Инструменты Swagger облегчают разработку на протяжении всего жизненного цикла API, включая проектирование, тестирование, развертывание и документацию.

Существует два подхода к разработке серверного кода: сначала дизайн и сначала код. Сообщество Swagger рекомендует подход сначала к дизайну. Однако подход «сначала код» принят организациями, в которых уже реализована существующая бизнес-логика.

Каковы ваши предпочтения?

Спасибо Максиму Кузнецову и Джулио Каполино за то, что показали мне захватывающие возможности Swagger!

Спасибо за прочтение. Я надеюсь, что это было полезно. Вы можете увидеть другие мои публикации в Medium здесь.