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
Sample project to demonstrate OpenAPI Swagger configuration in Guice grizzly jersey example.
We are going to write a small hello world maven application containing one REST api endpoint and will generate OpenAPI swagger documentation for it.
We will be mostly using Swagger Java Annotations for generating the Resource description.
Sample project generates OpenAPI swagger documentation in both JSON and YAML format.
Download the complete application from here
Dependencies: pom.xml
This file contains the OpenAPI high-level resource description. you can describe the same using Swagger Annotations.
<?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"
}
]
}
}Sample REST API Endpoint:
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();
}
}
Generated OpenAPI documentation - JSON
{
"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"
}
}
}
}
}
}Generated OpenAPI documentation - YAML
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
You can download the full application here:
You may also like to see
Advanced Java Multithreading Interview Questions & Answers
Type Casting Interview Questions and Answers In Java?
Exception Handling Interview Question-Answer
Method Overloading - Method Hiding Interview Question-Answer
How is ambiguous overloaded method call resolved in java?
Method Overriding rules in Java
Interface interview questions and answers in Java
Enjoy !!!!
If you find any issue in post or face any error while implementing, Please comment.
