Develop a microservice application with support for Swagger specification.
The objective of this sample is to demonstrate how to document API with Swagger/OpenAPI v2 compliant annotations. The tutorial will guide you through the necessary steps. You will add KumuluzEE dependencies into pom.xml. To enable support for Swagger annotations you will use kumuluzee-swagger extension. Required knowledge: basic familiarity with JAX-RS.
In order to run this example you will need the following:
-
Java 8 (or newer), you can use any implementation:
-
If you have installed Java, you can check the version by typing the following in a command line:
java -version
-
-
Maven 3.2.1 (or newer):
-
If you have installed Maven, you can check the version by typing the following in a command line:
mvn -version
-
-
Git:
-
If you have installed Git, you can check the version by typing the following in a command line:
git --version
-
This sample does not contain any prerequisites and can be started on its own.
The example uses maven to build and run the microservices.
-
Build the sample using maven:
$ cd kumuluzee-swagger $ mvn clean package
-
Run the sample:
-
Uber-jar:
$ java -jar target/${project.build.finalName}.jar
in Windows environemnt use the command
java -jar target/${project.build.finalName}.jar
-
Exploded:
$ java -cp target/classes:target/dependency/* com.kumuluz.ee.EeApplication
in Windows environment use the command
java -cp target/classes;target/dependency/* com.kumuluz.ee.EeApplication
The application/service can be accessed on the following URL:
- JAX-RS - http://localhost:8080/v1/customer
OpenAPI specification for APIs can be access on the following URL:
Swagger specification URL always follows the following URL template:
- http://<-hostname->:<-port->/api-specs//swagger.[json|yaml]
This tutorial will guide you through the steps required to document JAX-RS application using Swagger annotations.
Package contains two versions of JAX-RS application CustomersAPI.
CustomersAPI v1 JAX-RS resource:
- GET http://localhost:8080/v1/customer - list of all customers.
OpenAPI specification:
We will follow these steps:
- Create a Maven project in the IDE of your choice (Eclipse, IntelliJ, etc.)
- Add Maven dependencies to KumuluzEE and include KumuluzEE components (OpenAPI)
- Implement the JAX-RS resource using standard JAX-RS API
- Use Swagger annotations to document API
- Build the microservice
- Run it
Add the KumuluzEE BOM module dependency to your pom.xml
file:
<dependencyManagement>
<dependencies>
<dependency>
<groupId>com.kumuluz.ee</groupId>
<artifactId>kumuluzee-bom</artifactId>
<version>${kumuluz.version}</version>
<type>pom</type>
<scope>import</scope>
</dependency>
</dependencies>
</dependencyManagement>
Add the kumuluzee-swagger
dependency:
<dependency>
<groupId>com.kumuluz.ee.swagger</groupId>
<artifactId>kumuluzee-swagger</artifactId>
<version>${kumuluzee-swagger.varsion}</version>
</dependency>
Add the kumuluzee-maven-plugin
build plugin to package microservice as uber-jar:
<build>
<plugins>
<plugin>
<groupId>com.kumuluz.ee</groupId>
<artifactId>kumuluzee-maven-plugin</artifactId>
<version>${kumuluzee.version}</version>
<executions>
<execution>
<id>package</id>
<goals>
<goal>repackage</goal>
</goals>
</execution>
</executions>
</plugin>
</plugins>
</build>
or exploded:
<build>
<plugins>
<plugin>
<groupId>com.kumuluz.ee</groupId>
<artifactId>kumuluzee-maven-plugin</artifactId>
<version>${kumuluzee.version}</version>
<executions>
<execution>
<id>package</id>
<goals>
<goal>copy-dependencies</goal>
</goals>
</execution>
</executions>
</plugin>
</plugins>
</build>
Tutorial for the implementation of JAX-RS is described in jax-rs sample.
KumuluzEE-Swagger extension brings Swagger compliant annotations for documenting APIs.
@ApplicationPath("v1")
@SwaggerDefinition(info = @Info(title = "CustomersAPI", version = "v1.0.0"), host = "localhost:8080")
public class CustomerApplication extends Application {
}
@Path("customer")
@Api
@Produces(MediaType.APPLICATION_JSON)
public class CustomerResource {
@GET
@ApiOperation(value = "Get customers list", tags = {"customers"}, notes = "Returns a list of customers.")
@ApiResponses(value = {@ApiResponse(message = "List of customers", code = 200, response = Customer.class)})
public Response getCustomers() {
List<Customer> customers = new ArrayList<>();
Customer c = new Customer("1", "John", "Doe");
customers.add(c);
return Response.status(Response.Status.OK).entity(customers).build();
}
}
In case only one JAX-RS application is present in project no further configuration is necessary to make API specification accessible.
However, if we have two or more JAX-RS applications we have to provide additional information regarding resource packages for each application.
This is configured in xml<configuration>
section of kumuluzee-maven-plugin by providing:
<configuration>
<specificationConfig>
<includeSwaggerUI>true</includeSwaggerUI>
<apiSpecifications>
<apiSpecification>
<applicationPath>/v1</applicationPath>
<resourcePackages>
com.kumuluz.ee.samples.openapi.v1
</resourcePackages>
</apiSpecification>
<apiSpecification>
<applicationPath>/v2</applicationPath>
<resourcePackages>
com.kumuluz.ee.samples.openapi.v2
</resourcePackages>
</apiSpecification>
</apiSpecifications>
</specificationConfig>
</configuration>
By default Swagger-UI (visualization of specification) is not included in the build artifacts. To enable Swagger-UI set xml<includeSwaggerUI>true</includeSwaggerUI>
inside xml<specificationConfig>true</specificationConfig>
.
Swagger-UI is accessible at: http://localhost:8080/api-specs/ui
By default api-specs will be generated and exposed on /api-specs url. To disable swagger definitions and UI in runtime you can use configuration property kumuluzee.swagger.enabled and set it to false (see example in config.yaml).
To build the microservice and run the example, use the commands as described in previous sections.