Статьи

API автоматической публикации и мониторинга с Spring Boot

Декабрь 25, 2018

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

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

Spring Boot от Pivotal проложил путь к созданию облачных приложений на основе микросервисов с гибкой и минимальной кодировкой. Если вы хотите узнать больше о Spring Boot, загляните в этот блог Matt McCandless. Не требуется много усилий для реализации RESTful API для сервиса с Spring Boot. И размещение этого сервиса в инфраструктуре микросервисов также не требует особых усилий. (Смотрите нашу новую белую книгу для более.)

В этом блоге будет описано, как документацию Swagger / OpenAPI можно применить к реализации Spring Boot. Мы покажем, как документация и мониторинг API могут автоматически публиковаться на портале документации API.

В качестве примера мы представляем эталонное CRUD-приложение Spring Boot API (использующее Spring MVC / Data с Spring Fox) и настраиваем автоматическую публикацию документации и статистики API на портале документации GrokOla. В этом примере мы представляем две утилиты с открытым исходным кодом, которые помогают и позволяют опубликованным API-интерфейсам осуществлять поиск и уведомлять пользователей об изменениях.

Конфигурирование Swagger In Spring Boot с Spring Fox

OpenAPI (fka Swagger) — это спецификация документации API, которая позволяет извлекать API RESTful из реализаций кода. Возможно, это более эффективно, чем документировать API на отдельном этапе.

Spring Fox — это фреймворк, который автоматизирует генерацию документации Swagger JSON из приложений Spring Boot. Чтобы увидеть, как легко создавать документацию Swagger JSON из приложения Spring Boot, рассмотрим это простое приложение-службу Employee API, которое реализует CRUD API для сотрудников.

Реализацию CRUD API сотрудника можно найти в этом общедоступном репозитории github: https://github.com/in-the-keyhole/khs-spring-boot-api-example .

Пример приложения реализует следующие API с использованием Spring MVC. Сопоставление данных Spring с объектной моделью Employee с использованием Hibernate, настроенного для базы данных в памяти.

При запуске объекты Employee могут создаваться, считываться, обновляться и удаляться с помощью следующих API, определенных в частичной khs.exmaple.api.Api контроллера REST Spring khs.exmaple.api.Api показанной ниже.

01
02
03
04
05
06
07
08
09
10
11
12
13
14
15
16
17
18
19
20
21
22
23
@RestController
@RequestMapping("/api")
public class Api {
     
 
    @Autowired
    EmployeeService service;
     
     
    @RequestMapping(method = RequestMethod.GET, value = "/employees/{id}", produces = MediaType.APPLICATION_JSON_VALUE)
    ResponseEntity<Employee> employee(@PathVariable("id") Long id) {
        Employee employee = service.findEmployee(id);
        return new ResponseEntity<Employee>(employee, HttpStatus.OK);
    }
 
    @ApiOperation("value")
    @RequestMapping(method = RequestMethod.GET, value = "/employees", produces = MediaType.APPLICATION_JSON_VALUE)
    ResponseEntity<Iterable<Employee>> employees() {
        Iterable<Employee> employees = service.all();
        return new ResponseEntity<Iterable<Employee>>(employees, HttpStatus.OK);
    }
     
……..

Документация Swagger может быть произведена с использованием среды Spring Fox. Вот как это применяется к примеру приложения.

Добавьте в свой проект зависимость Spring Fox / Swagger Maven.

1
2
3
4
5
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.6.1</version>
</dependency>

Затем конфигурация Spring Fox определяется в классе SwaggerConfig.java вместе с аннотацией @EnableSwagger2 .

01
02
03
04
05
06
07
08
09
10
11
12
13
14
15
16
17
18
19
20
21
22
@Configuration
@EnableSwagger2
public class SwaggerConfig {
 
    @Bean
    public Docket apiDocket() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .paths(regex("/api.*"))
                .build();
    }
      
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Employee API Example")
                .description("A implementation of an API Gateway for Keyhole Labs Microservice Reference.")
                .contact(new Contact("Keyhole Software", "keyholesoftware.com", "asktheteam@keyholesoftware.com"))
                .version("2.0")
                .build();
    }
}

После настройки и запуска приложения документацию Swagger JSON можно получить по следующему URL-адресу: http://127.0.0.1:8080/v2/api-docs .

Автоматизированная публикация API

Обеспечение доступности Swagger API JSON для команд, необходимых для успеха, особенно если вы пытаетесь устранить препятствия, мешающие гибкости, и создаете организацию с кросс-функциональными командами (то есть «инвертирующим» закон Конвея).

Платформа Swagger может создавать удобочитаемую документацию HTML Swagger, однако она не индексируется / не может быть найдена, объединяется с другими API и не позволяет добавлять дополнительную документацию. Требуется лучший механизм.

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

Автоматизация этого шага необходима для принятия и предоставления ценности. Наши разработчики в Keyhole Software создали стартовую среду Spring Boot с открытым исходным кодом, которая будет публиковать Swagger на портале при каждом запуске приложения.

@PublishSwagger

После включения Spring Fox / Swagger вы можете применить стартовый каркас https://github.com/in-the-keyhole/khs-spring-boot-publish-swagger-starter, выполнив следующие шаги.

Добавьте следующую зависимость в ваш pom.xml .

1
2
3
4
5
<dependency>
  <groupId>com.keyholesoftware</groupId>                    
       <artifactId>khs-spring-boot-publish-swagger-starter</artifactId>
  <version>1.0.0</version>
</dependency>

Добавьте следующие свойства в ваш файл application.yml :

1
2
3
4
5
swagger:
  publish:
    publish-url: https://demo.grokola.com/swagger/publish/14
    security-token: 6e8f1cc6-3c53-4ebe-b496-53f19fb7e10e
    swagger-url: http://127.0.0.1:${server.port}/v2/api-docs

Примечание. Этот конфиг указывает на вики-портал GrokOla Demo API.

Добавьте аннотацию @PublishSwagger в свой класс startup Spring Boot.

1
2
3
4
5
6
7
@SpringBootApplication
@PublishSwagger
public class EmployeesApp {
    public static void main(String[] args) {
        SpringApplication.run(EmployeesApp.class, args);
    }
}

После запуска приложения Swagger JSON будет опубликован по указанному publish-url . В данном случае это демонстрационный сайт программного обеспечения вики-портала GroholeOk API Keyhole.

Вот импортированный API в GrokOla:

GrokOla — это вики, которая позволяет импортировать API-интерфейсы вручную и в автономном режиме. Этот блог показывает, как вы можете легко публиковать свои API с помощью Spring Boot. Однако с GrokOla вы также можете вручную импортировать API Swagger.

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

@EnableApiStats

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

Разработчики Spring Boot создали более сжатый и простой в применении механизм для получения и передачи статистики использования отдельных приложений API на портал для анализа. Это было реализовано как еще одна стартовая среда Spring Boot (общедоступная, с открытым исходным кодом), доступная на GitHub: https://github.com/in-the-keyhole/khs-spring-boot-api-statistics-starter .

Это решение применяется в следующих трех простых шагах.

Добавьте следующую зависимость в ваш POM.XML .

1
2
3
4
5
<dependency>
    <groupId>com.keyholesoftware</groupId>
    <artifactId>khs-spring-boot-api-statistics-starter</artifactId>
    <version>1.0.1</version>
</dependency>

Добавьте приведенную ниже конфигурацию в ваш application.yml . Это создаст статистику API для демонстрационного экземпляра GrokOla.

1
2
3
4
5
6
api:
  statistics:
    name: employeeapi
    pattern-match: /api/.*
    publish-url: https://demo.grokola.com/sherpa/api/stats/41
    token: 6e8f1cc6-3c53-4ebe-b496-53f19fb7e10e

Добавьте @EnableApiStatistics в реализацию boot main class приложения.

1
2
3
4
5
6
7
8
9
@SpringBootApplication
@PublishSwagger
@EnableApiStatistics
public class EmployeesApp {
 
    public static void main(String[] args) {
        SpringApplication.run(EmployeesApp.class, args);
    }
}

Когда приложение запускается после каждых десяти запросов к API, собранные статистические данные об использовании отправляются в publish-url . Количество запросов перед отправкой на URL настраивается. Это делается в отдельном потоке, чтобы не снижать производительность.

Вот консоль примера приложения после десяти запросов API:

Обратите внимание, что API JSON отправляется на опубликованный URL.

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

Представление « Usage показывает тип маршрутов API, рассчитывает общую и среднюю продолжительность. Это позволяет разработчикам определять, что и как долго используются их API. Вы также можете просмотреть популярность и где и когда используются API.

Последние мысли

Автоматическая публикация документации по API без каких-либо проблем и предоставление возможности отслеживать их поведение очень важны для успеха вашей платформы на основе сервисов.

Автоматизированная публикация и мониторинг API укрепит стиль архитектуры Microservices и обеспечит гибкость предприятия. Доступная документация по API должна легко обнаруживаться, так как информация, передаваемая по всему предприятию, эффективно определяет, где используются API, как часто используются API и когда API меняются.

Мы выпустили две утилиты с открытым исходным кодом, которые должны помочь в достижении этой цели:

  • Spring Boot Starter для публикации Swagger / OpenAPI на портале при каждом запуске приложения.
    • https://github.com/in-the-keyhole/khs-spring-boot-publish-swagger-starter
    • Этот стартер Spring Boot можно использовать для POST Swagger JSON для цели публикации (URL) при запуске приложения Spring Boot. Тело запроса будет необработанным Swagger JSON, и токен безопасности может быть применен для обеспечения доступа только авторизованным клиентам.
  • Spring Boot Starter для публикации статистики использования API отдельных приложений на портале для анализа.
    • https://github.com/in-the-keyhole/khs-spring-boot-api-statistics-starter
    • Этот стартер Spring Boot можно использовать для статистики использования POST API для цели публикации (URL) через настраиваемый интервал. Тело запроса будет массивом статистики JSON, и можно применить маркер безопасности, чтобы гарантировать, что доступ имеют только авторизованные клиенты.

Мы надеемся, что вы найдете это полезным!

Ссылка: Auto-Publishing & Monitoring API с Spring Boot от нашего партнера JCG Дэвида Питта в блоге Keyhole Software .
74
Share: