Непрерывная разработка Restful API с использованием спецификации OpenAPI

По мере того, как все больше людей принимают сервис-ориентированную архитектуру и улучшают интеграцию с внешними системами, возникла необходимость писать Restful API для наших сервисов. Во время строительства мы часто можем столкнуться с несколькими проблемами, такими как:

• Стандартный и согласованный дизайн API
• Лучшая документация
• Клиентские библиотеки
• Игровая площадка (лучший опыт разработчика)

Поэтому при написании API мы должны убедиться, что он придерживается стандартного принципа проектирования, обновить документацию (размещенную в другом месте) и, наконец, написать клиентские библиотеки (сложнее, если вам нужно поддерживать несколько языков). Делать все это вручную - болезненная работа.

Вероятно, у нас есть Спецификация OpenAPI (ранее известная как swagger), которая предлагает нам стандартный, не зависящий от языка интерфейс для написания RESTful API, который позволяет как людям, так и компьютерам понимать возможности сервиса.

Вы можете прочитать об этом больше, там много контента, вот официальный сайт,

Короче говоря, вы можете определить API в файле JSON или YAML, который можно легко преобразовать в код или документацию.

В этой статье мы рассмотрим, как мы можем работать со спецификацией OpenAPI, генерировать код и использовать его на сервере и на стороне клиента.

Настройка:

В этом примере мы будем использовать java & gradle, но идея такая же для других языков или сред. Сначала создайте проект Gradle Java petstore-api из выбранной IDE, я использую IntelliJ, Gradle 5.

Простой простой Java-проект, вы также можете удалить исходную папку java из проекта, так как мы не собираемся писать код :). Этот проект служит обычным местом для хранения контракта API (только определения, без кода) и библиотек, которые можно использовать непосредственно в службе, где мы пишем фактические API, а также создаем клиентские библиотеки.

API:

Для API мы будем использовать образец petstore, представленный на сайте OpenAPI, он определяет API для создания и получения информации о питомце.

Создайте новый файл petstore-api.yml в resources папке и скопируйте и вставьте содержимое сверху либо через gist, либо из Github.

Добавление подключаемого модуля генератора OpenAPI:

Это простая часть, официальный репозиторий открытого API -generator содержит информацию о том, как его использовать, для настройки Gradle прочтите Gradle Plugin, скопируйте и вставьте следующий контент в свой build.gradle файл,

Вот разбивка приведенного выше кода,

buildPetStoreJavaClient: это настраиваемая задача Gradle, которая расширяется от openApiGenerate задачи, предоставляемой плагином openapi-generator, который используется для генерации кода с помощью генератора инструментов Open API для Open API 2.0 или 3. x спецификационные документы.

• generatorName: представляет, какой генератор использовать для создания кода, мы используем java, есть несколько других генераторов, таких как Go, Koltin, Spring и т. Д. , посмотрите Список генераторов. Таким образом, вы можете сгенерировать код для разных языков, для клиентов или серверов и т. Д.
• можно настроить несколько других конфигураций, таких как имя пакета, определения артефактов и т. д., для получения дополнительной информации проверьте Конфигурации
• configOptions: определяет конфигурацию, которую необходимо передать генератору, может различаться для каждого генератора, поскольку в нашем случае это java, мы настраиваем его для использования библиотеки дат java8 , Jackson для сериализации, включите BeanValidation и т. д. Для получения дополнительной информации проверьте Конфигурации Java.

generateCode: Я написал вспомогательную задачу, которая копирует сгенерированную документацию из папки сгенерированный в корневую папку документов, чтобы мы могли добавить ее в git. Примечание: эта задача добавляет buildPetStoreJavaClient в качестве зависимости

и мы добавили generateCode в качестве зависимости для задачи compileJava, поэтому каждый раз, когда мы компилируем код, генерируется,

compileJava.dependsOn(generateCode)

Попробуем, запустим задачу compileJava,

./gradlew clean compileJava

код будет сгенерирован в каталоге build/java-client,

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

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

// attach the generated folder as source for this project
sourceSets {
    main {
        java {
            srcDir "$buildDir/java-client/src/main/java"
        }
    }
}

Также теперь, когда ваш сгенерированный код является текущим исходным кодом проекта, если вы скомпилируете сейчас, вы получите ошибки, потому что зависимости, используемые этими кодами, не были определены в текущем проекте, добавьте следующее.
ПРИМЕЧАНИЕ: это требуется исключительно для создания библиотеки.

// these dependencies are required for the generated code in order to build
ext {
    swagger_annotations_version = "1.5.22"
    jackson_version = "2.9.9"
    jackson_databind_version = "2.9.9"
    spring_web_version = "4.3.9.RELEASE"
    jodatime_version = "2.9.9"
    junit_version = "4.12"
    validation_version = "2.0.1.Final"
}

dependencies {
    compile "io.swagger:swagger-annotations:$swagger_annotations_version"
    compile "com.google.code.findbugs:jsr305:3.0.2"
    compile "org.springframework:spring-web:$spring_web_version"
    compile "com.fasterxml.jackson.core:jackson-core:$jackson_version"
    compile "com.fasterxml.jackson.core:jackson-annotations:$jackson_version"
    compile "com.fasterxml.jackson.core:jackson-databind:$jackson_databind_version"
    compile "com.fasterxml.jackson.jaxrs:jackson-jaxrs-json-provider:$jackson_version"
    compile "com.fasterxml.jackson.datatype:jackson-datatype-jsr310:$jackson_version"
    testCompile "junit:junit:$junit_version"
    compile group: 'javax.annotation', name: 'javax.annotation-api', version: '1.3.2'
    compile "javax.validation:validation-api:$validation_version"
}

Итак, полный файл build.gradle должен выглядеть так:

А теперь, на момент истины, когда вы запускаете команду build, вы получаете красивую клиентскую библиотеку java под bulid/libs,

./gradlew clean build

Вы можете загрузить библиотеку в artifactory, maven central, GitHub и т. Д. Для использования другими разработчиками или даже для вашего собственного сервиса (подробнее об этом позже).

Точно так же вы можете создавать библиотеки для других языков, поэтому другие разработчики могут легко создавать код, просто используя определение YAML API.

Полный исходный код api-контракта с настройкой доступен на Github,

Внесение изменений в API:

Поскольку определение api размещено в отдельном репозитории, разработчики могут легко вносить изменения в разные ветки и создавать запросы на извлечение. Таким образом, каждое изменение можно безопасно просмотреть, проверить на качество дизайна и прочее.
Теперь мы можем настроить конвейеры сборки для создания библиотек, загрузки артефактов, обновления документации - все с помощью одной команды.

Генерация серверного кода:

Что еще интереснее, openapi-generator может также генерировать код на стороне сервера, используя то же определение API (petstore-api.yml), что не только ускоряет процесс разработки, но и помогает серверу придерживаться те же стандартные определения API и соответствует им. Так что больше не будет отсутствующей синхронизации между серверным API, его документацией и клиентской реализацией :)

Давайте быстро создадим новый проект petstore-server с той же конфигурацией сборки с небольшими изменениями в генераторе,

Я создал его как приложение spring -boot, но вы можете использовать любую структуру по вашему выбору и соответственно сгенерировать код API.

Мой файл build.gradle выглядит так:

Если вы проверите задачу buildPetStoreServerCode, на этот раз мы используем spring в качестве нашего генератора, и некоторые изменения, связанные с этим генератором, по большей части останутся прежними. Проверьте нашу Конфигурацию пружинного генератора

Теперь мы можем просто создать контроллер PetsApiController, который реализует интерфейс PetsApi, сгенерированный открытым API-генератором.

Обратите внимание: все модели PetsApi, Pet, определения методов основаны на сгенерированном коде, и теперь наша жизнь становится намного проще!

Полный код сервера доступен на Github,

Детская площадка:

Да, мы тоже это понимаем. Пользовательский интерфейс Swagger - это пользовательский интерфейс с открытым исходным кодом для взаимодействия с файлом определения OpenAPI, мы можем разместить его самостоятельно или с помощью SwaggerHub.

Мы также можем просмотреть его в Интернете, перейти на http://editor.swagger.io, скопировать и вставить определение API или импортировать из URL Petstore API Spec. Вы получите красивый и модный интерфейс.

Заключение

Благодаря спецификации OpenAPI мы можем:

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

У OpenAPI есть несколько других инструментов, которые могут вас заинтересовать, посмотрите Инструменты OpenAPI

Удачных API сборки…

Ссылка:

• Https://swagger.io/specification
• Https://github.com/OpenAPITools/openapi-generator
• Https://swagger.io
• Https://github.com/ramesh-dev/petstore-demo-api
• Https://github.com/ramesh-dev/petstore-demo-server