Swagger OpenAPI REST API Java Example using Guice and Jersey
In this post we will see how to integrate Swagger in Guice and Jersey to dynamically generate OpenAPI REST endpoint documentation.
Sample project uses below libraries,1. Google Guice2. Jersey2. Grizzly server3. Swagger OpenAPI Annotations
We are going to write a small hello world maven application containing one REST api endpoint and will generate OpenAPI swagger documentation for it.
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
<modelVersion>4.0.0</modelVersion>
<groupId>com.javabypatel</groupId>
<artifactId>guice-grizzly-jersey-openapi-swagger-example</artifactId>
<version>1.0-SNAPSHOT</version>
<properties>
<grizzly.version>2.3.16</grizzly.version>
<jersey.version>2.30</jersey.version>
<guice.version>4.2.2</guice.version>
<guice.bridge>2.5.0-b61</guice.bridge>
<swagger.version>2.1.5</swagger.version>
<maven.compiler.source>11</maven.compiler.source>
<maven.compiler.target>11</maven.compiler.target>
</properties>
<dependencies>
<!-- Guice dependencies -->
<dependency>
<groupId>com.google.inject</groupId>
<artifactId>guice</artifactId>
<version>${guice.version}</version>
</dependency>
<dependency>
<groupId>org.glassfish.hk2</groupId>
<artifactId>guice-bridge</artifactId>
<version>${guice.bridge}</version>
</dependency>
<!-- Jersey dependencies -->
<dependency>
<groupId>org.glassfish.jersey.bundles</groupId>
<artifactId>jaxrs-ri</artifactId>
<version>${jersey.version}</version>
</dependency>
<dependency>
<groupId>org.glassfish.jersey.containers</groupId>
<artifactId>jersey-container-grizzly2-http</artifactId>
<version>${jersey.version}</version>
</dependency>
<dependency>
<groupId>org.glassfish.jersey.ext</groupId>
<artifactId>jersey-bean-validation</artifactId>
<version>${jersey.version}</version>
</dependency>
<dependency>
<groupId>org.glassfish.jersey.inject</groupId>
<artifactId>jersey-hk2</artifactId>
<version>${jersey.version}</version>
</dependency>
<!-- swagger dependencies -->
<dependency>
<groupId>io.swagger.core.v3</groupId>
<artifactId>swagger-jaxrs2</artifactId>
<version>${swagger.version}</version>
</dependency>
<dependency>
<groupId>io.swagger.core.v3</groupId>
<artifactId>swagger-annotations</artifactId>
<version>${swagger.version}</version>
</dependency>
<dependency>
<groupId>io.swagger.core.v3</groupId>
<artifactId>swagger-core</artifactId>
<version>${swagger.version}</version>
</dependency>
</dependencies>
</project>
<project xmlns="http://maven.apache.org/POM/4.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
<modelVersion>4.0.0</modelVersion>
<groupId>com.javabypatel</groupId>
<artifactId>guice-grizzly-jersey-openapi-swagger-example</artifactId>
<version>1.0-SNAPSHOT</version>
<properties>
<grizzly.version>2.3.16</grizzly.version>
<jersey.version>2.30</jersey.version>
<guice.version>4.2.2</guice.version>
<guice.bridge>2.5.0-b61</guice.bridge>
<swagger.version>2.1.5</swagger.version>
<maven.compiler.source>11</maven.compiler.source>
<maven.compiler.target>11</maven.compiler.target>
</properties>
<dependencies>
<!-- Guice dependencies -->
<dependency>
<groupId>com.google.inject</groupId>
<artifactId>guice</artifactId>
<version>${guice.version}</version>
</dependency>
<dependency>
<groupId>org.glassfish.hk2</groupId>
<artifactId>guice-bridge</artifactId>
<version>${guice.bridge}</version>
</dependency>
<!-- Jersey dependencies -->
<dependency>
<groupId>org.glassfish.jersey.bundles</groupId>
<artifactId>jaxrs-ri</artifactId>
<version>${jersey.version}</version>
</dependency>
<dependency>
<groupId>org.glassfish.jersey.containers</groupId>
<artifactId>jersey-container-grizzly2-http</artifactId>
<version>${jersey.version}</version>
</dependency>
<dependency>
<groupId>org.glassfish.jersey.ext</groupId>
<artifactId>jersey-bean-validation</artifactId>
<version>${jersey.version}</version>
</dependency>
<dependency>
<groupId>org.glassfish.jersey.inject</groupId>
<artifactId>jersey-hk2</artifactId>
<version>${jersey.version}</version>
</dependency>
<!-- swagger dependencies -->
<dependency>
<groupId>io.swagger.core.v3</groupId>
<artifactId>swagger-jaxrs2</artifactId>
<version>${swagger.version}</version>
</dependency>
<dependency>
<groupId>io.swagger.core.v3</groupId>
<artifactId>swagger-annotations</artifactId>
<version>${swagger.version}</version>
</dependency>
<dependency>
<groupId>io.swagger.core.v3</groupId>
<artifactId>swagger-core</artifactId>
<version>${swagger.version}</version>
</dependency>
</dependencies>
</project>
openapi-configuration.json
This file contains the OpenAPI high-level resource description. you can describe the same using Swagger Annotations.
{
"resourcePackages": [
"com.javabypatel.resource"
],
"prettyPrint": true,
"cacheTTL": 0,
"openAPI": {
"info": {
"version": "1.0.0",
"title": "Guice Grizzly Jersey Openapi Swagger Example API",
"description": "OpenAPI swagger configuration example in sample project that uses Guice, Grizzly, Jersey.",
"contact": {
"email": "jayeshmaheshpatel@gmail.com"
},
"license": {
"name": "MIT License",
"url": "https://en.wikipedia.org/wiki/MIT_License"
}
},
"servers": [
{
"url": "http://localhost:8080/OpenAPIExample/",
"description": "Guice Grizzly Jersey Openapi Swagger Example API server"
}
]
}
}
package com.javabypatel.resource;
import com.javabypatel.model.GreetResponse;
import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.Parameter;
import io.swagger.v3.oas.annotations.enums.ParameterIn;
import io.swagger.v3.oas.annotations.media.ArraySchema;
import io.swagger.v3.oas.annotations.media.Content;
import io.swagger.v3.oas.annotations.media.Schema;
import io.swagger.v3.oas.annotations.responses.ApiResponse;
import javax.ws.rs.BadRequestException;
import javax.ws.rs.GET;
import javax.ws.rs.Path;
import javax.ws.rs.Produces;
import javax.ws.rs.core.Context;
import javax.ws.rs.core.MediaType;
import javax.ws.rs.core.Response;
import javax.ws.rs.core.UriInfo;
@Path("greet")
public class GreetResource {
private static final String GREET_MESSAGE = "Hello";
@GET
@Produces(MediaType.APPLICATION_JSON)
@Operation(
summary = "This is a sample test API to greet user.",
parameters = {
@Parameter(in = ParameterIn.QUERY, name = "name")
},
responses = {
@ApiResponse(
responseCode = "200",
description = "Greeted successfully.",
content = @Content(
mediaType = MediaType.APPLICATION_JSON,
array = @ArraySchema(schema = @Schema(implementation = GreetResponse.class))
)
),
@ApiResponse(
responseCode = "400",
description = "Bad request. Request is not well formed."
)
}
)
public Response greet(@Context UriInfo uriInfo) {
if (!uriInfo.getQueryParameters().containsKey("name")) {
throw new BadRequestException("'name' query parameter is missing.");
}
return Response
.ok()
.entity(new GreetResponse(GREET_MESSAGE + " " + uriInfo.getQueryParameters().getFirst("name")))
.build();
}
}
{
"openapi" : "3.0.1",
"info" : {
"title" : "Guice Grizzly Jersey Openapi Swagger Example API",
"description" : "OpenAPI swagger configuration example in sample project that uses Guice, Grizzly, Jersey.",
"contact" : {
"email" : "jayeshmaheshpatel@gmail.com"
},
"license" : {
"name" : "MIT License",
"url" : "https://en.wikipedia.org/wiki/MIT_License"
},
"version" : "1.0.0"
},
"servers" : [ {
"url" : "http://localhost:8080/OpenAPIExample/",
"description" : "Guice Grizzly Jersey Openapi Swagger Example API server"
} ],
"paths" : {
"/greet" : {
"get" : {
"summary" : "This is a sample test API to greet user.",
"operationId" : "greet",
"parameters" : [ {
"name" : "name",
"in" : "query",
"schema" : {
"type" : "string"
}
} ],
"responses" : {
"200" : {
"description" : "Greeted successfully.",
"content" : {
"application/json" : {
"schema" : {
"type" : "array",
"items" : {
"$ref" : "#/components/schemas/GreetResponse"
}
}
}
}
},
"400" : {
"description" : "Bad request. Request is not well formed."
}
}
}
}
},
"components" : {
"schemas" : {
"GreetResponse" : {
"type" : "object",
"properties" : {
"message" : {
"type" : "string"
}
}
}
}
}
}
openapi: 3.0.1
info:
title: Guice Grizzly Jersey Openapi Swagger Example API
description: "OpenAPI swagger configuration example in sample project that uses\
\ Guice, Grizzly, Jersey."
contact:
email: jayeshmaheshpatel@gmail.com
license:
name: MIT License
url: https://en.wikipedia.org/wiki/MIT_License
version: 1.0.0
servers:
- url: http://localhost:8080/OpenAPIExample/
description: Guice Grizzly Jersey Openapi Swagger Example API server
paths:
/greet:
get:
summary: This is a sample test API to greet user.
operationId: greet
parameters:
- name: name
in: query
schema:
type: string
responses:
"200":
description: Greeted successfully.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/GreetResponse'
"400":
description: Bad request. Request is not well formed.
components:
schemas:
GreetResponse:
type: object
properties:
message:
type: string