Swagger OpenAPI REST Java Example using Guice and Jersey

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 Guice

2. Jersey

2. Grizzly server

3. 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

https://github.com/javabypatel/guice-grizzly-jersey-openapi-swagger-example

Dependencies: pom.xml

<?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>

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:

https://github.com/javabypatel/guice-grizzly-jersey-openapi-swagger-example

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.