Swagger with JAX-RS in a Spring Boot

Integrating Swagger UI (SpringFox) with JAX-RS in a Spring Boot Application

In the world of RESTful APIs, documentation is crucial for both developers and consumers of the API. Swagger UI provides a powerful interface for visualizing and interacting with your API's endpoints. In this blog post, we will explore how to integrate Swagger UI (using SpringFox) with a Spring Boot application that utilizes JAX-RS for building RESTful services. 

Swagger UI (SpringFox) with JAX-RS in a Spring Boot Application

What is Swagger UI?

Swagger UI is a collection of HTML, JavaScript, and CSS assets that dynamically generate beautiful documentation from a Swagger-compliant API. It allows developers to visualize and interact with the API's resources without having any implementation logic in place.

What is SpringFox?

SpringFox is a library that automates the generation of Swagger documentation for Spring-based applications. It provides a set of annotations and configurations that make it easy to document your RESTful services.

Setting Up Your Spring Boot Application

Step 1: Create a Spring Boot Project

You can create a Spring Boot project using Spring Initializr (https://start.spring.io/) or your favorite IDE. Make sure to include the following dependencies:

• Spring Web
• SpringFox Swagger 2
• JAX-RS (e.g., Jersey)

Step 2: Add Dependencies

In your pom.xml, add the following dependencies:

<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>
<dependency>
    <groupId>org.glassfish.jersey.containers</groupId>
    <artifactId>jersey-container-servlet-core</artifactId>
    <version>2.34</version>
</dependency>

Step 3: Configure Swagger

Create a configuration class to set up Swagger. This class will enable Swagger and configure the API documentation.

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.api"))
                .paths(PathSelectors.any())
                .build();
    }
}

Step 4: Create a JAX-RS Resource

Now, let's create a simple JAX -RS resource to expose some endpoints.

import javax.ws.rs.GET;
import javax.ws.rs.Path;
import javax.ws.rs.Produces;
import javax.ws.rs.core.MediaType;

@Path("/hello")
public class HelloResource {

    @GET
    @Produces(MediaType.APPLICATION_JSON)
    public String sayHello() {
        return "{"message": "Hello, World!"}";
    }
}

Step 5: Register JAX-RS in Spring Boot

You need to register your JAX-RS application in Spring Boot. Create a configuration class for JAX-RS.

import org.glassfish.jersey.server.ResourceConfig;
import org.springframework.context.annotation.Configuration;

@Configuration
public class JerseyConfig extends ResourceConfig {
    public JerseyConfig() {
        packages("com.example.api");
    }
}

Step 6: Run Your Application

Run your Spring Boot application. You can access the Swagger UI at http://localhost:8080/swagger-ui.html and the API documentation at http://localhost:8080/v2/api-docs.

Text-Based Diagrams

Application Structure

MySpringBootApp
│
├── src
│   ├── main
│   │   ├── java
│   │   │   └── com
│   │   │       └── example
│   │   │           ├── api
│   │   │           │   └── HelloResource.java
│   │   │           ├── config
│   │   │           │   ├── SwaggerConfig.java
│   │   │           │   └── JerseyConfig.java
│   │   │           └── MySpringBootApp.java
│   │   └── resources
│   │       └── application.properties
│   └── test
│       └── java
│           └── com
│               └── example
│                   └── MySpringBootAppTests.java

API Endpoints

GET /hello
└── Response: 
    {
        "message": "Hello, World!"
    }

Conclusion

Integrating Swagger UI with JAX-RS in a Spring Boot application enhances the development experience by providing clear and interactive API documentation. By following the steps outlined in this blog post, you can easily set up Swagger UI to document your RESTful services, making it easier for both developers and consumers to understand and utilize your API effectively. With the power of SpringFox and JAX-RS, you can ensure that your API is well-documented and accessible.