Blog about Java, Microservices, Spring, Containers and more
Quarkus is a lightweight Java framework developed by RedHat. It is dedicated for cloud-native applications that require a small memory footprint and a fast startup time. Its programming model is built on top of proven standards like Eclipse MicroProfile. Recently it is growing in popularity. It may be considered as an alternative to Spring Boot framework, especially if you are running your applications on Kubernetes or OpenShift. Continue reading “Guide to Quarkus with Kotlin”
I have already written about documentation for microservices more than two years ago in my article Microservices API Documentation with Swagger2. In that case I used project SpringFox for auto-generating Swagger documentation for Spring Boot applications. Since that time the SpringFox library is not being actively developed by the maintainers – the latest version has been released on June 2018. Currently, the most important problems with this library are a lack of support for OpenAPI in the newest version 3, and for Spring reactive APIs built using WebFlux. All these features are implemented by Springdoc OpenAPI library. Therefore, it may threaten as a replacement for SpringFox as Swagger and OpenAPI 3 generation tool for Spring Boot applications. Continue reading “Microservices API Documentation with Springdoc OpenAPI”
You may find many examples of microservices built with Spring Boot on my blog, but the most of them is written in Java. With the rise in popularity of Kotlin language it is more often used with Spring Boot for building backend services. Starting with version 5 Spring Framework has introduced first-class support for Kotlin. In this article I’m going to show you example of microservice build with Kotlin and Spring Boot 2. I’ll describe some interesting features of Spring Boot, which can treated as a set of good practices when building backend, REST-based microservices. Continue reading “Kotlin Microservice with Spring Boot”
Recently, I have come across some articles and mentions about Spring REST Docs, where it has been present as a better alternative to traditional Swagger docs. Until now, I was always using Swagger for building API documentation, so I decided to try Spring REST Docs. You may even read on the main page of that Spring project (https://spring.io/projects/spring-restdocs) some references to Swagger, for example: “This approach frees you from the limitations of the documentation produced by tools like Swagger”. Are you interested in building API documentation using Spring REST Docs? Let’s take a closer look on that project!
A first difference in comparison to Swagger is a test-driven approach to generating API documentation. Thanks to that Spring REST Docs ensures that the documentation is always generated accurately matches the actual behavior of the API. When using Swagger SpringFox library you just need to enable it for the project and provide some configuration to force it work following your expectations. I have already described usage of Swagger 2 for automated build API documentation for Spring Boot based application in my two previous articles:
The articles mentioned above describe in the details how to use SpringFox Swagger in your Spring Boot application to automatically generate API documentation basing on the source code. Here I’ll give you only a short introduction to that technology, to easily find out differences between usage of Swagger2 and Spring REST Docs.
To enable SpringFox library for your application you need to include the following dependencies to pom.xml.
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>
Then you should annotate the main or configuration class with @EnableSwagger2. You can also customize the behaviour of SpringFox library by declaring Docket bean.
@Bean
public Docket swaggerEmployeeApi() {
return new Docket(DocumentationType.SWAGGER_2)
.select()
.apis(RequestHandlerSelectors.basePackage("pl.piomin.services.employee.controller"))
.paths(PathSelectors.any())
.build()
.apiInfo(new ApiInfoBuilder().version("1.0").title("Employee API").description("Documentation Employee API v1.0").build());
}
Now, after running the application the documentation is available under context path /v2/api-docs. You can also display it in your web browser using Swagger UI available at site /swagger-ui.html.
It looks easy? Let’s see how to do this with Spring REST Docs.
There are some other differences between Spring REST Docs and SpringFox Swagger. By default, Spring REST Docs uses Asciidoctor. Asciidoctor processes plain text and produces HTML, styled and layed out to suit your needs. If you prefer, Spring REST Docs can also be configured to use Markdown. This really distinguished it from Swagger, which uses its own notation called OpenAPI Specification.
Spring REST Docs makes use of snippets produced by tests written with Spring MVC’s test framework, Spring WebFlux’s WebTestClient or REST Assured 3. I’ll show you an example based on Spring MVC.
I suggest you begin from creating base Asciidoc file. It should be placed in src/main/asciidoc directory in your application source code. I don’t know if you are familiar with Asciidoctor notation, but it is really intuitive. The sample visible below shows two important things. First we’ll display the version of the project taken from pom.xml. Then we’ll include the snippets generated during JUnit tests by declaring macro called operation containing document name and list of snippets. We can choose between such snippets like curl-request, http-request, http-response, httpie-request, links, request-body, request-fields, response-body, response-fields or path-parameters. The document name is determined by name of the test method in our JUnit test class.
= RESTful Employee API Specification
{project-version}
:doctype: book
== Add a new person
A `POST` request is used to add a new person
operation::add-person[snippets='http-request,request-fields,http-response']
== Find a person by id
A `GET` request is used to find a new person by id
operation::find-person-by-id[snippets='http-request,path-parameters,http-response,response-fields']
The source code fragment with Asciidoc natation is just a template. We would like to generate HTML file, which prettily displays all our automatically generated staff. To achieve it we should enable plugin asciidoctor-maven-plugin in the project’s pom.xml. In order to display Maven project version we need to pass it to the Asciidoc plugin configuration attributes. We also need to spring-restdocs-asciidoctor dependency to that plugin.
<plugin>
<groupId>org.asciidoctor</groupId>
<artifactId>asciidoctor-maven-plugin</artifactId>
<version>1.5.6</version>
<executions>
<execution>
<id>generate-docs</id>
<phase>prepare-package</phase>
<goals>
<goal>process-asciidoc</goal>
</goals>
<configuration>
<backend>html</backend>
<doctype>book</doctype>
<attributes>
<project-version>${project.version}</project-version>
</attributes>
</configuration>
</execution>
</executions>
<dependencies>
<dependency>
<groupId>org.springframework.restdocs</groupId>
<artifactId>spring-restdocs-asciidoctor</artifactId>
<version>2.0.0.RELEASE</version>
</dependency>
</dependencies>
</plugin>
Ok, the documentation is automatically generated during Maven build from our api.adoc file located inside src/main/asciidoc directory. But we still need to develop JUnit API tests that automatically generate required snippets. Let’s do that in the next step.
First, we should enable Spring REST Docs for our project. To achieve it we have to include the following dependency.
<dependency> <groupId>org.springframework.restdocs</groupId> <artifactId>spring-restdocs-mockmvc</artifactId> <scope>test</scope> </dependency>
Now, all we need to do is to implement JUnit tests. Spring Boot provides an @AutoConfigureRestDocs annotation that allows you to leverage Spring REST Docs in your tests.
In fact, we need to prepare standard Spring MVC test using MockMvc bean. I also mocked some methods implemented by EmployeeRepository. Then, I used some static methods provided by Spring REST Docs with support for generating documentation of request and response payloads. First of those method is document("{method-name}/",...), which is responsible for generating snippets under directory target/generated-snippets/{method-name}, where method name is the name of the test method formatted using kebab-case. I have described all the JSON fields in the requests using requestFields(...) and responseFields(...) methods.
@RunWith(SpringRunner.class)
@WebMvcTest(EmployeeController.class)
@AutoConfigureRestDocs
public class EmployeeControllerTest {
@MockBean
EmployeeRepository repository;
@Autowired
MockMvc mockMvc;
private ObjectMapper mapper = new ObjectMapper();
@Before
public void setUp() {
Employee e = new Employee(1L, 1L, "John Smith", 33, "Developer");
e.setId(1L);
when(repository.add(Mockito.any(Employee.class))).thenReturn(e);
when(repository.findById(1L)).thenReturn(e);
}
@Test
public void addPerson() throws JsonProcessingException, Exception {
Employee employee = new Employee(1L, 1L, "John Smith", 33, "Developer");
mockMvc.perform(post("/").contentType(MediaType.APPLICATION_JSON).content(mapper.writeValueAsString(employee)))
.andExpect(status().isOk())
.andDo(document("{method-name}/", requestFields(
fieldWithPath("id").description("Employee id").ignored(),
fieldWithPath("organizationId").description("Employee's organization id"),
fieldWithPath("departmentId").description("Employee's department id"),
fieldWithPath("name").description("Employee's name"),
fieldWithPath("age").description("Employee's age"),
fieldWithPath("position").description("Employee's position inside organization")
)));
}
@Test
public void findPersonById() throws JsonProcessingException, Exception {
this.mockMvc.perform(get("/{id}", 1).accept(MediaType.APPLICATION_JSON))
.andExpect(status().isOk())
.andDo(document("{method-name}/", responseFields(
fieldWithPath("id").description("Employee id"),
fieldWithPath("organizationId").description("Employee's organization id"),
fieldWithPath("departmentId").description("Employee's department id"),
fieldWithPath("name").description("Employee's name"),
fieldWithPath("age").description("Employee's age"),
fieldWithPath("position").description("Employee's position inside organization")
), pathParameters(parameterWithName("id").description("Employee id"))));
}
}
If you would like to customize some settings of Spring REST Docs you should provide @TestConfiguration class inside JUnit test class. In the following code fragment you may see an example of such customization. I overridden default snippets output directory from index to test method-specific name, and force generation of sample request and responses using prettyPrint option (single parameter in the separated line).
@TestConfiguration
static class CustomizationConfiguration implements RestDocsMockMvcConfigurationCustomizer {
@Override
public void customize(MockMvcRestDocumentationConfigurer configurer) {
configurer.operationPreprocessors()
.withRequestDefaults(prettyPrint())
.withResponseDefaults(prettyPrint());
}
@Bean
public RestDocumentationResultHandler restDocumentation() {
return MockMvcRestDocumentation.document("{method-name}");
}
}
Now, if you execute mvn clean install on your project you should see the following structure inside your output directory.
Once we have successfully built our project, the documentation has been generated. We can display HTML file available at target/generated-docs/api.html. It provides the full documentation of our API.
And the next part…
You may also want to publish it inside your application fat JAR file. If you configure maven-resources-plugin following example vibisle below it would be available under /static/docs directory inside JAR.
<plugin>
<artifactId>maven-resources-plugin</artifactId>
<executions>
<execution>
<id>copy-resources</id>
<phase>prepare-package</phase>
<goals>
<goal>copy-resources</goal>
</goals>
<configuration>
<outputDirectory>
${project.build.outputDirectory}/static/docs
</outputDirectory>
<resources>
<resource>
<directory>
${project.build.directory}/generated-docs
</directory>
</resource>
</resources>
</configuration>
</execution>
</executions>
</plugin>
That’s all what I wanted to show in this article. The sample service generating documentation using Spring REST Docs is available on GitHub under repository https://github.com/piomin/sample-spring-microservices-new/tree/rest-api-docs/employee-service. I’m not sure that Swagger and Spring REST Docs should be treated as a competitive solutions. I use Swagger for simple testing an API on the running application or exposing specification that can be used for automated generation of a client code. Spring REST Docs is rather used for generating documentation that can be published somewhere, and “is accurate, concise, and well-structured. This documentation then allows your users to get the information they need with a minimum of fuss”. I think there is no obstacle to use Spring REST Docs and SpringFox Swagger together in your project in order to provide the most valuable documentation of API exposed by the application.
One thing’s for sure. If you don’t have to version your API, do not try to do that. However, sometimes you have to. A large part of the most popular services like Twitter, Facebook, Netflix or PayPal is versioning their REST APIs. The advantages and disadvantages of that approach are obvious. On the one hand you don’t have to worry about making changes in your API even if many external clients and applications consume it. But on the other hand, you have maintain different versions of API implementation in your code, what sometimes may be troublesome.
In this article I’m going to show you how to maintain the several versions of REST API in your application in the most comfortable way. We will base on the sample application written on the top of Spring Boot framework and exposing API documentation using Swagger and SpringFox libraries.
Spring Boot does not provide any dedicated solutions for versioning APIs. The situation is different for SpringFox Swagger2 library, which provides grouping mechanism from version 2.8.0, which is perfect for generating documentation of versioned REST API.
I have already introduced Swagger2 together with Spring Boot application in one of my previous posts. In the article Microservices API Documentation with Swagger2 you may read how to use Swagger2 for generating API documentation for all the independent microservices and publishing it in one place – on API Gateway.
There are some different ways to provide an API versioning in your application. The most popular of them are:
curl -H "Accept: application/vnd.piomin.v1+json" http://localhost:8080/api/personsThe decision, which of that approach implement in the application is up to you. We would discuss the advantages and disadvantages of every single approach, however it is not the main purpose of that article. The main purpose is to show you how to implement versioning in Spring Boot application and then publish the API documentation automatically using Swagger2. The sample application source code is available on GitHub (https://github.com/piomin/sample-api-versioning.git). I have implemented two of the approaches described above – in point 1 and 4.
Swagger2 can be enabled in Spring Boot application by including SpringFox library. In fact, this is the suite of java libraries used for automating the generation of machine and human readable specifications for JSON APIs written using Spring Framework. It supports such formats like swagger, RAML and jsonapi. To enable it for your application include the following Maven dependencies to the project: io.springfox:springfox-swagger-ui, io.springfox:springfox-swagger2, io.springfox:springfox-spring-web. Then you will have to annotate the main class with @EnableSwagger2 and define Docker object. Docket is a Springfox’s primary configuration mechanism for Swagger 2.0. We will discuss the details about it in the next section along with the sample for each way of versioning API.
Our sample API is very simple. It exposes basic CRUD methods for Person entity. There are three versions of API available for external clients: 1.0, 1.1 and 1.2. In the version 1.1 I have changed the method for updating Person entity. In version 1.0 it was available under /person path, while now it is available under /person/{id} path. This is the only difference between versions 1.0 and 1.1. There is also one only difference in API between versions 1.1 and 1.2. Instead of field birthDate it returns age as integer parameter. This change affects to all the endpoints except DELETE /person/{id}. Now, let’s proceed to the implementation.
Here’s the full implementation of URI path versioning inside Spring @RestController.
@RestController
@RequestMapping("/person")
public class PersonController {
@Autowired
PersonMapper mapper;
@Autowired
PersonRepository repository;
@PostMapping({"/v1.0", "/v1.1"})
public PersonOld add(@RequestBody PersonOld person) {
return (PersonOld) repository.add(person);
}
@PostMapping("/v1.2")
public PersonCurrent add(@RequestBody PersonCurrent person) {
return mapper.map((PersonOld) repository.add(person));
}
@PutMapping("/v1.0")
@Deprecated
public PersonOld update(@RequestBody PersonOld person) {
return (PersonOld) repository.update(person);
}
@PutMapping("/v1.1/{id}")
public PersonOld update(@PathVariable("id") Long id, @RequestBody PersonOld person) {
return (PersonOld) repository.update(person);
}
@PutMapping("/v1.2/{id}")
public PersonCurrent update(@PathVariable("id") Long id, @RequestBody PersonCurrent person) {
return mapper.map((PersonOld) repository.update(person));
}
@GetMapping({"/v1.0/{id}", "/v1.1/{id}"})
public PersonOld findByIdOld(@PathVariable("id") Long id) {
return (PersonOld) repository.findById(id);
}
@GetMapping("/v1.2/{id}")
public PersonCurrent findById(@PathVariable("id") Long id) {
return mapper.map((PersonOld) repository.findById(id));
}
@DeleteMapping({"/v1.0/{id}", "/v1.1/{id}", "/v1.2/{id}"})
public void delete(@PathVariable("id") Long id) {
repository.delete(id);
}
}
If you would like to have three different versions available in the single generated API specification you should declare three Docket @Beans – one per single version. In this case the swagger group concept, which has been already introduced by SpringFox, would be helpful for us. The reason this concept bas been introduced is a necessity for support applications which require more than one swagger resource listing. Usually you need more than one resource listing in order to provide different versions of the same API. We can assign group to every Docket just by invoking groupName DSL method on it. Because different versions of API method are implemented within the same controller, we have to distinguish them by declaring path regex matching the selected version. All other settings are standard.
@Bean
public Docket swaggerPersonApi10() {
return new Docket(DocumentationType.SWAGGER_2)
.groupName("person-api-1.0")
.select()
.apis(RequestHandlerSelectors.basePackage("pl.piomin.services.versioning.controller"))
.paths(regex("/person/v1.0.*"))
.build()
.apiInfo(new ApiInfoBuilder().version("1.0").title("Person API").description("Documentation Person API v1.0").build());
}
@Bean
public Docket swaggerPersonApi11() {
return new Docket(DocumentationType.SWAGGER_2)
.groupName("person-api-1.1")
.select()
.apis(RequestHandlerSelectors.basePackage("pl.piomin.services.versioning.controller"))
.paths(regex("/person/v1.1.*"))
.build()
.apiInfo(new ApiInfoBuilder().version("1.1").title("Person API").description("Documentation Person API v1.1").build());
}
@Bean
public Docket swaggerPersonApi12() {
return new Docket(DocumentationType.SWAGGER_2)
.groupName("person-api-1.2")
.select()
.apis(RequestHandlerSelectors.basePackage("pl.piomin.services.versioning.controller"))
.paths(regex("/person/v1.2.*"))
.build()
.apiInfo(new ApiInfoBuilder().version("1.2").title("Person API").description("Documentation Person API v1.2").build());
}
Now, we may display Swagger UI for our API just by calling URL in the web browser path /swagger-ui.html. You can switch between all available versions of API as you can see on the picture below.
Specification is generated by the exact version of API. Here’s documentation for version 1.0. Because method PUT /person is annotated with @Deprecated it is crossed out on the generated HTML documentation page.
If you switch to group person-api-1 you will see all the methods that contains v1.1 in the path. Along them you may recognize the current version of PUT method with {id} field in the path.
When using documentation generated by Swagger you may easily call every method after expanding it. Here’s the sample of calling method PUT /person/{id} from implemented for version 1.2.
To access the implementation of versioning witt ‘Accept’ header you should switch to branch header (https://github.com/piomin/sample-api-versioning/tree/header). Here’s the full implementation of content negotiation using ‘Accept’ header versioning inside Spring @RestController.
@RestController
@RequestMapping("/person")
public class PersonController {
@Autowired
PersonMapper mapper;
@Autowired
PersonRepository repository;
@PostMapping(produces = {"application/vnd.piomin.app-v1.0+json", "application/vnd.piomin.app-v1.1+json"})
public PersonOld add(@RequestBody PersonOld person) {
return (PersonOld) repository.add(person);
}
@PostMapping(produces = "application/vnd.piomin.app-v1.2+json")
public PersonCurrent add(@RequestBody PersonCurrent person) {
return mapper.map((PersonOld) repository.add(person));
}
@PutMapping(produces = "application/vnd.piomin.app-v1.0+json")
@Deprecated
public PersonOld update(@RequestBody PersonOld person) {
return (PersonOld) repository.update(person);
}
@PutMapping(value = "/{id}", produces = "application/vnd.piomin.app-v1.1+json")
public PersonOld update(@PathVariable("id") Long id, @RequestBody PersonOld person) {
return (PersonOld) repository.update(person);
}
@PutMapping(value = "/{id}", produces = "application/vnd.piomin.app-v1.2+json")
public PersonCurrent update(@PathVariable("id") Long id, @RequestBody PersonCurrent person) {
return mapper.map((PersonOld) repository.update(person));
}
@GetMapping(name = "findByIdOld", value = "/{idOld}", produces = {"application/vnd.piomin.app-v1.0+json", "application/vnd.piomin.app-v1.1+json"})
@Deprecated
public PersonOld findByIdOld(@PathVariable("idOld") Long id) {
return (PersonOld) repository.findById(id);
}
@GetMapping(name = "findById", value = "/{id}", produces = "application/vnd.piomin.app-v1.2+json")
public PersonCurrent findById(@PathVariable("id") Long id) {
return mapper.map((PersonOld) repository.findById(id));
}
@DeleteMapping(value = "/{id}", produces = {"application/vnd.piomin.app-v1.0+json", "application/vnd.piomin.app-v1.1+json", "application/vnd.piomin.app-v1.2+json"})
public void delete(@PathVariable("id") Long id) {
repository.delete(id);
}
}
We still have to define three Docker @Beans, but the filtering criterias are slightly different. The simple filtering by path is not an option here. We have to crate Predicate for RequestHandler object and pass it to apis DSL method. The predicate implementation should filter every method in order to find only those which have produces field with required version number. Here’s sample Docket implementation for version 1.2.
@Bean
public Docket swaggerPersonApi12() {
return new Docket(DocumentationType.SWAGGER_2)
.groupName("person-api-1.2")
.select()
.apis(p -> {
if (p.produces() != null) {
for (MediaType mt : p.produces()) {
if (mt.toString().equals("application/vnd.piomin.app-v1.2+json")) {
return true;
}
}
}
return false;
})
.build()
.produces(Collections.singleton("application/vnd.piomin.app-v1.2+json"))
.apiInfo(new ApiInfoBuilder().version("1.2").title("Person API").description("Documentation Person API v1.2").build());
}
As you can see on the picture below the generated methods does not have the version number in the path.
When calling method for the selected version of API the only difference is in the response’s required content type.
Versioning is one of the most important concept around HTTP APIs designing. No matter which approach to versioning you choose you should do everything to describe your API well. This seems to be especially important in the era of microservices, where your interface may be called by many other independent applications. In this case creating documentation in isolation from the source code could be troublesome. Swagger solves all of described problems. It may be easily integrated with your application, supports versioning. Thanks to SpringFox project it also can be easily customized in your Spring Boot application to meet more advanced demands.
Swagger is the most popular tool for designing, building and documenting RESTful APIs. It has nice integration with Spring Boot. To use it in conjunction with Spring we need to add following two dependencies to Maven pom.xml.
<dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.6.1</version> </dependency> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>2.6.1</version> </dependency>
Swagger configuration for single Spring Boot service is pretty simple. The level of complexity is greater if you want to create one documentation for several separated microservices. Such documentation should be available on API gateway. In the picture below you can see the architecture of our sample solution.
First, we should configure Swagger on every microservice. To enable it we have to declare @EnableSwagger2 on the main class. API documentation will be automatically generated from source code by Swagger library during application startup. The process is controlled by Docket @Bean which is also declared in the main class. API version is read from pom.xml file using MavenXpp3Reader. We also set some other properties like title, author and description using apiInfo method. By default, Swagger generates documentation for all REST services including those created by Spring Boot. We would like to limit documentation only to our @RestController located inside pl.piomin.microservices.advanced.account.api package.
@Bean
public Docket api() throws IOException, XmlPullParserException {
MavenXpp3Reader reader = new MavenXpp3Reader();
Model model = reader.read(new FileReader("pom.xml"));
return new Docket(DocumentationType.SWAGGER_2)
.select()
.apis(RequestHandlerSelectors.basePackage("pl.piomin.microservices.advanced.account.api"))
.paths(PathSelectors.any())
.build().apiInfo(new ApiInfo("Account Service Api Documentation", "Documentation automatically generated", model.getParent().getVersion(), null, new Contact("Piotr Mińkowski", "piotrminkowski.wordpress.com", "piotr.minkowski@gmail.com"), null, null));
}
Here’s our API RESTful controller.
@RestController
public class AccountController {
@Autowired
AccountRepository repository;
protected Logger logger = Logger.getLogger(AccountController.class.getName());
@RequestMapping(value = "/accounts/{number}", method = RequestMethod.GET)
public Account findByNumber(@PathVariable("number") String number) {
logger.info(String.format("Account.findByNumber(%s)", number));
return repository.findByNumber(number);
}
@RequestMapping(value = "/accounts/customer/{customer}", method = RequestMethod.GET)
public List findByCustomer(@PathVariable("customer") String customerId) {
logger.info(String.format("Account.findByCustomer(%s)", customerId));
return repository.findByCustomerId(customerId);
}
@RequestMapping(value = "/accounts", method = RequestMethod.GET)
public List findAll() {
logger.info("Account.findAll()");
return repository.findAll();
}
@RequestMapping(value = "/accounts", method = RequestMethod.POST)
public Account add(@RequestBody Account account) {
logger.info(String.format("Account.add(%s)", account));
return repository.save(account);
}
@RequestMapping(value = "/accounts", method = RequestMethod.PUT)
public Account update(@RequestBody Account account) {
logger.info(String.format("Account.update(%s)", account));
return repository.save(account);
}
}
The similar Swagger’s configuration exists on every microservice. API documentation is available under http://localhost:/swagger-ui.html. Now, we would like to enable one documentation embedded on the gateway for all microservices. Here’s Spring @Component implementing SwaggerResourcesProvider interface which overrides default provider configuration exists in Spring context.
@Component
@Primary
@EnableAutoConfiguration
public class DocumentationController implements SwaggerResourcesProvider {
@Override
public List get() {
List resources = new ArrayList<>();
resources.add(swaggerResource("account-service", "/api/account/v2/api-docs", "2.0"));
resources.add(swaggerResource("customer-service", "/api/customer/v2/api-docs", "2.0"));
resources.add(swaggerResource("product-service", "/api/product/v2/api-docs", "2.0"));
resources.add(swaggerResource("transfer-service", "/api/transfer/v2/api-docs", "2.0"));
return resources;
}
private SwaggerResource swaggerResource(String name, String location, String version) {
SwaggerResource swaggerResource = new SwaggerResource();
swaggerResource.setName(name);
swaggerResource.setLocation(location);
swaggerResource.setSwaggerVersion(version);
return swaggerResource;
}
}
All microservices api-docs are added as Swagger resources. The location address is proxied via Zuul gateway. Here’s gateway route configuration.
zuul:
prefix: /api
routes:
account:
path: /account/**
serviceId: account-service
customer:
path: /customer/**
serviceId: customer-service
product:
path: /product/**
serviceId: product-service
transfer:
path: /transfer/**
serviceId: transfer-service
Now, API documentation is available under gateway address http://localhost:8765/swagger-ui.html. You can see how it looks for account service in the picture below. We can select source service in the combo box placed inside title panel.
Documentation appearence can be easily customized by providing UIConfiguration @Bean. In the code below I changed default operations expansion level by setting “list” as a second constructor parameter – docExpansion.
@Bean
UiConfiguration uiConfig() {
return new UiConfiguration("validatorUrl", "list", "alpha", "schema",
UiConfiguration.Constants.DEFAULT_SUBMIT_METHODS, false, true, 60000L);
}
You can expand every operation to see the details. Every operation can be test by providing required parameters and clicking Try it out! button.
Sample application source code is available on GitHub.
Piotr's TechBlog 