If you are heading down the path of a Microservices style of architecture, one tenant you will need to embrace is automation. Many moving parts are introduced with this style of architecture. If successful, your environment will have a plethora of service APIs available that the enterprise can consume for application development and integration.
This means that there must be a way that available API documentation can be discovered. API information needs to be effectively communicated throughout the enterprise that shows where APIs are used, how often APIs are used, and when APIs change. Not having this type of monitoring in place will hinder and possibly cripple the agility benefits that a Microservice style of architecture can bring to the enterprise.
Spring Boot by Pivotal has led the way in providing a path to develop Microservices-based, cloud-ready applications in an agile and minimal coding manner. If you want to find out more about Spring Boot, check out this blog by Matt McCandless. It doesn’t take much effort to implement a RESTful API for a service with Spring Boot. And, putting that service in a Microservices infrastructure does not take much effort either. (See our newest white paper for more.)
This blog will describe how Swagger/OpenAPI documentation can be applied to a Spring Boot implementation. We will show how API documentation and monitoring can be automatically published to an API documentation portal.
As an example, we introduce a reference Spring Boot API CRUD application (using Spring MVC/Data with Spring Fox) and set up the automatic publishing of API documentation and statistics to documentation portal GrokOla. In the example, we introduce two open source utilities to help and allow published APIs the ability to be searched and notify users when changed.
Configuring Swagger In Spring Boot With Spring Fox
OpenAPI (fka Swagger) is an API documentation specification that allows RESTful APIs to be gleaned from code implementations. This is arguably more efficient than having to document APIs in a separate step.
Spring Fox is a framework that automates the generation of Swagger JSON documentation from Spring Boot applications. To see how easy it is to produce Swagger JSON documentation from a Spring Boot application, consider this simple Employee API Service application that implements a CRUD API for employees.
The employee CRUD API implementation can be found at this public github repository: https://github.com/in-the-keyhole/khs-spring-boot-api-example.
The example application implements the following APIs using Spring MVC. Spring Data mapping to an Employee object model using Hibernate that is configured for an in-memory database.
When started, Employee objects can be created, read, updated, and deleted with the following APIs defined in the partial khs.exmaple.api.Api Spring REST controller implementation shown below.
@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 documentation can be produced using the Spring Fox framework. Here is how it is applied to the example application.
Add the Spring Fox/Swagger Maven dependency to your project.
<dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.6.1</version> </dependency>
Then a Spring Fox config is defined in a SwaggerConfig.java class along with the @EnableSwagger2 annotation.
@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();
}
}Once configured and the application started, Swagger JSON documentation can be obtained with this URL: http://127.0.0.1:8080/v2/api-docs.
Automated API Publishing
Making Swagger API JSON available for teams to consume essential for success, especially if you are trying to eliminate agility-hindering silos and creating an organization with cross-functional teams (i.e. “inverting” Conway’ Law).
The Swagger framework can produce human-readable HTML Swagger documentation, however it is not indexable/searchable, aggregated with other APIs, and does not allow additional documentation to be added. A better mechanism is required.
Ideally this will be a developer API portal that will aggregate available APIs for an organization, index APIs for searchability, allow developers to easily add additional documentation, and provide usage metrics and notifications when APIs change.
Automating this step is essential for acceptance and providing value. Our developers at Keyhole Software have created an open source Spring Boot starter framework that will publish Swagger to a portal every time the application is started.
@PublishSwagger
Once you have Spring Fox/Swagger enabled, you can apply the https://github.com/in-the-keyhole/khs-spring-boot-publish-swagger-starter starter framework with the following steps.
Add the following dependency to your pom.xml.
<dependency>
<groupId>com.keyholesoftware</groupId>
<artifactId>khs-spring-boot-publish-swagger-starter</artifactId>
<version>1.0.0</version>
</dependency>Add the following properties your application.yml file:
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-docsNote: This config is pointing to the GrokOla Demo API Wiki Portal.
Add the @PublishSwagger annotation to your Spring Boot startup class.
@SpringBootApplication
@PublishSwagger
public class EmployeesApp {
public static void main(String[] args) {
SpringApplication.run(EmployeesApp.class, args);
}
}When the application is started, Swagger JSON will be published to the specified publish-url. In this case it is Keyhole’s GrokOla API wiki portal software’s demo site.
Here is the imported API in GrokOla:
GrokOla is a wiki that allows APIs to be imported manually and in a headless, automated manner. This blog shows how you can easily publish your APIs using Spring Boot. However, with GrokOla, you can also manually import Swagger APIs.
You can obtain a demo user id at this link. The example in this blog is already configured to point to this demo site. So, if you have an idea, you can play around with the API wiki portal.
@EnableApiStats
Just having readily-available API documentation is not enough to govern your APIs. Seeing who, how, and when they are used is critical. There are tools and sniffers that you can use to route and filter network activity, but this is a separate piece of software deployed to a location that has to be configured, typically by operations personnel and not the developer.
A more succinct and easy-to-apply mechanism has be created for Spring Boot developers to obtain & emit individual application API usage statistics to a portal for analysis. This has been implemented as another Spring Boot starter (public, open source) framework available on GitHub: https://github.com/in-the-keyhole/khs-spring-boot-api-statistics-starter.
This solution applied in the following three easy steps.
Add the following dependency to your POM.XML.
<dependency> <groupId>com.keyholesoftware</groupId> <artifactId>khs-spring-boot-api-statistics-starter</artifactId> <version>1.0.1</version> </dependency>
Add the configuration below to your application.yml. This will emit an API’s stats to the GrokOla demo instance.
api:
statistics:
name: employeeapi
pattern-match: /api/.*
publish-url: https://demo.grokola.com/sherpa/api/stats/41
token: 6e8f1cc6-3c53-4ebe-b496-53f19fb7e10eAdd the @EnableApiStatistics to your application boot main class implementation.
@SpringBootApplication
@PublishSwagger
@EnableApiStatistics
public class EmployeesApp {
public static void main(String[] args) {
SpringApplication.run(EmployeesApp.class, args);
}
}When the application starts, after every ten requests against the API, collected usage stats will be emitted to the publish-url. The number of requests before emission to the URL is configurable. This is done on a separate thread as not to inhibit performance.
Here is the console of the example application after ten API requests:
Notice, the API JSON being sent to the published URL.
GrokOla has been outfitted to accept the emitted API JSON stream and provide usage statistics to the user by associating API usage with published. This is accessible from the API documentation section of GrokOla. A screenshot for this API stats view is shown below.
The Usage view shows API routes type counts total duration and average duration. This allows developers to determine what and how long their APIs are being used. You can also view popularity and where and when APIs are being used.
Final Thoughts
Automatically publishing your API documentation in a seamless manner, and providing a way to monitor their usage behavior is critical to the success of your services-based platform.
Having automated API publishing & monitoring will strengthen a Microservices style of architecture and bring agility to the enterprise. Available API documentation should be easily discoverable, with information effectively communicated throughout the enterprise dictating where APIs are used, how often APIs are used, and when APIs change.
We have released two open source utilities that should help in this goal:
- Spring Boot Starter for publish Swagger/OpenAPI to a portal every time the application is started.
- https://github.com/in-the-keyhole/khs-spring-boot-publish-swagger-starter
- This Spring Boot starter can be used to POST Swagger JSON to a publishing target (URL) upon startup of the Spring Boot application. The body of the request will be the raw Swagger JSON, and a security token can be applied to ensure that only authorized clients have access.
- Spring Boot Starter for publishing individual application API usage statistics to a portal for analysis.
- https://github.com/in-the-keyhole/khs-spring-boot-api-statistics-starter
- This Spring Boot starter can be used to POST API usage statistics to a publishing target (URL) on a configurable interval. The body of the request will be a JSON array of statistics, and a security token can be applied to ensure that only authorized clients have access.
We hope that you find this helpful!
| Reference: | Auto-Publishing & Monitoring APIs With Spring Boot from our JCG partner David Pitt at the Keyhole Software blog. |
