如果您正在沿着微服务风格的架构前进，那么您将需要接受的一个租户就是自动化。 这种架构风格介绍了许多活动部件。 如果成功，您的环境将具有大量服务API，企业可以将其用于应用程序开发和集成。

这意味着必须有一种方法可以发现可用的API文档。 需要在整个企业范围内有效地传达API信息，以显示使用API​​的位置，使用API​​的频率以及更改API的时间。 如果没有这种类型的监视，将阻碍甚至可能削弱微服务风格的体系结构可以为企业带来的敏捷性收益。

Pivotal的Spring Boot引领了以敏捷且最少的编码方式开发基于微服务，云就绪应用程序的途径。 如果您想了解有关Spring Boot的更多信息，请查看Matt McCandless撰写的此博客 。 使用Spring Boot为服务实现RESTful API不需要太多的工作。 而且，将该服务置于微服务基础架构中也不需要太多工作。 （有关更多信息，请参见我们最新的白皮书 。）

该博客将介绍如何将Swagger / OpenAPI文档应用于Spring Boot实现。 我们将展示如何自动将API文档和监视发布到API文档门户。

作为示例，我们介绍了一个参考Spring Boot API CRUD应用程序（将Spring MVC / Data与Spring Fox一起使用），并将API文档和统计信息自动发布到文档门户GrokOla。 在示例中，我们引入了两个开源实用程序来帮助并允许已发布的API能够搜索并在更改时通知用户。

使用Spring Fox在Spring Boot中配置Swagger

OpenAPI（fka Swagger）是API文档规范，它允许从代码实现中收集RESTful API。 可以说，这比必须在单独的步骤中记录API更为有效。

Spring Fox是一个框架，可以自动从Spring Boot应用程序生成Swagger JSON文档。 要了解从Spring Boot应用程序生成Swagger JSON文档有多么容易，请考虑这个简单的Employee API Service应用程序，该应用程序为员工实现了CRUD API。

可以在以下公共github存储库中找到员工CRUD API的实现： https : //github.com/in-the-keyhole/khs-spring-boot-api-example 。

该示例应用程序使用Spring MVC实现了以下API。 Spring Data使用为内存数据库配置的Hibernate映射到Employee对象模型。

启动后，可以使用下面显示的部分khs.exmaple.api.Api Spring REST控制器实现中定义的以下API创建，读取，更新和删除Employee对象。

@RestController
@RequestMapping("/api")
public class Api {@AutowiredEmployeeService 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);}……..

可以使用Spring Fox框架生成Swagger文档。 这是将其应用于示例应用程序的方式。

将Spring Fox / Swagger Maven依赖项添加到您的项目中。

<dependency><groupId>io.springfox</groupId><artifactId>springfox-swagger2</artifactId><version>2.6.1</version>
</dependency>

然后在SwaggerConfig.java类中定义Spring Fox配置以及@EnableSwagger2批注。

@Configuration
@EnableSwagger2
public class SwaggerConfig {@Beanpublic 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();}
}

配置完成并启动应用程序后，可以使用以下URL获得Swagger JSON文档： http : //127.0.0.1 : 8080/v2/api-docs 。

自动化API发布

使Swagger API JSON供团队使用，以消耗成功所必需的东西，尤其是在您试图消除阻碍敏捷性的孤岛并创建具有跨职能团队的组织（即“颠倒” Conway'法）的情况下。

Swagger框架可以生成人类可读HTML Swagger文档，但是它不可索引/不可搜索，无法与其他API聚合，并且不允许添加其他文档。 需要更好的机制。

理想情况下，这将是一个开发人员API门户，它将汇总组织的可用API，为可搜索性编制索引API，允许开发人员轻松添加其他文档以及在API更改时提供使用指标和通知。

自动化此步骤对于接受和提供价值至关重要。 我们在Keyhole Software的开发人员已经创建了一个开源Spring Boot启动程序框架，该框架将在每次启动应用程序时将Swagger发布到门户。

@PublishSwagger

启用S​​pring Fox / Swagger后，可以通过以下步骤应用https://github.com/in-the-keyhole/khs-spring-boot-publish-swagger-starter入门框架。

将以下依赖项添加到pom.xml 。

<dependency><groupId>com.keyholesoftware</groupId>                     <artifactId>khs-spring-boot-publish-swagger-starter</artifactId> <version>1.0.0</version>
</dependency>

将以下属性添加到application.yml文件中：

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

注意：此配置指向GrokOla演示API Wiki门户。

将@PublishSwagger批注添加到您的Spring Boot startup类中。

@SpringBootApplication
@PublishSwagger
public class EmployeesApp {public static void main(String[] args) {SpringApplication.run(EmployeesApp.class, args);}
}

启动应用程序后，Swagger JSON将发布到指定的publish-url 。 在这种情况下，它是Keyhole的GrokOla API Wiki门户软件的演示站点。

这是GrokOla中导入的API：

GrokOla是一个Wiki，它允许以无头的自动化方式手动导入API。 该博客显示了如何使用Spring Boot轻松发布API。 但是，使用GrokOla，您也可以手动导入Swagger API。

您可以通过此链接获取演示用户ID。 该博客中的示例已经配置为指向该演示站点。 因此，如果您有想法，可以使用API​​ Wiki门户。

@EnableApiStats

仅拥有随时可用的API文档不足以管理您的API。 了解谁，如何以及何时使用它们至关重要。 您可以使用一些工具和嗅探器来路由和过滤网络活动，但这是一个单独的软件，部署到必须由操作人员而非开发人员配置的位置。

已经为Spring Boot开发人员创建了一种更为简洁和易于应用的机制，以获取并向门户发布各个应用程序API使用情况统计信息，以进行分析。 这已实现为另一个可在GitHub上使用的Spring Boot启动程序（公共，开源）框架： https ： //github.com/in-the-keyhole/khs-spring-boot-api-statistics-starter 。

此解决方案通过以下三个简单步骤应用。

将以下依赖项添加到POM.XML 。

<dependency><groupId>com.keyholesoftware</groupId><artifactId>khs-spring-boot-api-statistics-starter</artifactId><version>1.0.1</version>
</dependency>

将以下配置添加到application.yml 。 这将向GrokOla演示实例发出API的统计信息。

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

将@EnableApiStatistics添加到您的应用程序boot main class实现中。

@SpringBootApplication
@PublishSwagger
@EnableApiStatistics
public class EmployeesApp {public static void main(String[] args) {SpringApplication.run(EmployeesApp.class, args);}
}

当应用程序启动时，针对API的每十次请求后，收集到的使用情况统计信息将被发送到publish-url 。 发送到URL之前的请求数是可配置的。 这是在单独的线程上完成的，以免影响性能。

这是十个API请求后示例应用程序的控制台：

注意，API JSON被发送到已发布的U​​RL。

GrokOla已准备好接受发出的API JSON流，并通过将API使用情况与已发布相关联来向用户提供使用情况统计信息。 可从GrokOla的API文档部分进行访问。 此API统计信息视图的屏幕截图如下所示。

“ Usage视图显示API路由类型计数总持续时间和平均持续时间。 这使开发人员可以确定使用其API的时间和时间。 您还可以查看受欢迎程度以及使用API​​的时间和地点。

最后的想法

以无缝方式自动发布API文档，并提供一种监视其使用行为的方法，对于成功实现基于服务的平台至关重要。

具有自动化的API发布和监视功能将增强微服务架构风格，并为企业带来敏捷性。 可用的API文档应该易于发现，并且在整个企业中有效地传达信息，从而决定使用API​​的位置，使用频率的API以及更改API的时间。

我们已经发布了两个开源工具，可以帮助实现这一目标：

• Spring Boot Starter，用于在每次启动应用程序时将Swagger / OpenAPI发布到门户。
  • https://github.com/in-the-keyhole/khs-spring-boot-publish-swagger-starter
• Spring Boot Starter，用于将各个应用程序API使用情况统计信息发布到门户以进行分析。
  • https://github.com/in-the-keyhole/khs-spring-boot-api-statistics-starter

希望对您有所帮助！

翻译自: https://www.javacodegeeks.com/2017/03/auto-publishing-monitoring-apis-spring-boot.html