Если вы идете по пути архитектуры стиля 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@EnableSwagger2public 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.") .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@PublishSwaggerpublic 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@EnableApiStatisticspublic 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 . |