This tutorial will guide you through the process of integrating Swagger UI into your Jakarta EE project. We will cover the necessary steps to configure Swagger in a Jakarta EE environment, enabling you to automatically generate and serve API documentation for your RESTful services.
Requirements
In today’s API-driven development landscape, clear and concise documentation is crucial for the successful adoption and maintenance of web services. Swagger, a widely recognized open-source framework, simplifies the process of designing, building, and documenting RESTful APIs. With SwaggerUI, developers can generate interactive and user-friendly API documentation directly from the source code, making it easier for both developers and stakeholders to explore and understand the API endpoints.
In this tutorial we will show how to implement Swagger UI in the following Jakarta EE project: REST CRUD application with JPA | A complete example
In order to enable Swagger UI you need to complete a set of steps
Step 1: Integrate Swagger UI in your Web project
The Swagger UI Project is available at the following URL: https://github.com/swagger-api/swagger-ui
Download the project and copy the dist folder in the src/main/webapp/swagger folder of your project. You should have the following project structure after copying the folder:
├───src │ └───main │ ├───java │ │ └───com │ │ └───mastertheboss │ │ └───jaxrs │ │ Customer.java │ │ CustomerEndpoint.java │ │ CustomerException.java │ │ CustomerRepository.java │ │ JaxRsActivator.java │ │ │ ├───resources │ │ │ import.sql │ │ │ │ │ └───META-INF │ │ persistence.xml │ │ │ └───webapp │ │ index.html │ │ │ ├───swagger │ │ └───dist │ │ favicon-16x16.png │ │ favicon-32x32.png │ │ index.css │ │ index.html │ │ oauth2-redirect.html │ │ swagger-initializer.js . . . . │ │ swagger-ui.css │ │ swagger-ui.css.map │ │ swagger-ui.js │ │ swagger-ui.js.map │ │ │ └───WEB-INF │ beans.xml │ web.xml
Next, pick up the swagger-initializer.js page and specify the URL of your API Docs:
window.ui = SwaggerUIBundle({
url: "http://localhost:8080/jaxrs-demo/rest/openapi.json",
dom_id: '#swagger-ui',
deepLinking: true,
presets: [
SwaggerUIBundle.presets.apis,
SwaggerUIStandalonePreset
],
plugins: [
SwaggerUIBundle.plugins.DownloadUrl
],
layout: "StandaloneLayout"
});
This step is not mandatory though. You can still point to a different openapi.json definition from the top of your Swagger UI.
Step 2: Include Swagger UI Libraries
In order to be able to use Swagger UI with OpenAPI, you need to include the swagger-annotations , swagger-jaxrs2-jakarta and swagger-jaxrs2-servlet-initializer-jakarta library to your project, in addition to the Jakarta EE library.
<dependency>
<groupId>io.swagger.core.v3</groupId>
<artifactId>swagger-annotations</artifactId>
<version>2.2.21</version>
</dependency>
<dependency>
<groupId>io.swagger.core.v3</groupId>
<artifactId>swagger-jaxrs2-jakarta</artifactId>
<version>2.2.21</version>
</dependency>
<dependency>
<groupId>io.swagger.core.v3</groupId>
<artifactId>swagger-jaxrs2-servlet-initializer-jakarta</artifactId>
<version>2.2.21</version>
</dependency>
Also, define a mapping for the OpenApiServlet with an init parameter matching to your project namespace:
<servlet>
<servlet-name>OpenApi</servlet-name>
<servlet-class>io.swagger.v3.jaxrs2.integration.OpenApiServlet</servlet-class>
<init-param>
<param-name>openApi.configuration.resourcePackages</param-name>
<param-value>com.mastertheboss.jaxrs</param-value>
</init-param>
</servlet>
<servlet-mapping>
<servlet-name>OpenApi</servlet-name>
<url-pattern>/openapi/*</url-pattern>
</servlet-mapping>
Step 3: Applying Swagger API annotations ( Optional )
Finally, you can apply Swagger annotations to provide a clean description of your REST Endpoint Operations. For example:
import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.media.Content;
import io.swagger.v3.oas.annotations.media.Schema;
import io.swagger.v3.oas.annotations.parameters.RequestBody;
import io.swagger.v3.oas.annotations.responses.ApiResponse;
import io.swagger.v3.oas.annotations.responses.ApiResponses;
import io.swagger.v3.oas.annotations.tags.Tag;
import jakarta.ws.rs.*;
import jakarta.ws.rs.core.Response;
import jakarta.enterprise.context.ApplicationScoped;
import javax.inject.Inject;
import java.util.List;
@Path("customers")
@ApplicationScoped
@Produces("application/json")
@Consumes("application/json")
@Tag(name = "Customer", description = "Operations related to customers")
public class CustomerEndpoint {
@Inject
CustomerRepository customerRepository;
@GET
@Operation(summary = "Get all customers", description = "Returns a list of all customers.")
@ApiResponses(value = {
@ApiResponse(responseCode = "200", description = "Successfully retrieved list",
content = @Content(mediaType = "application/json",
schema = @Schema(implementation = Customer.class))),
@ApiResponse(responseCode = "500", description = "Internal server error")
})
// Other endpoint methods
}
In a nutshell:
@Tag: Describes the category of the endpoints, which helps in organizing the Swagger documentation.
@Operation: Describes the operation (endpoint), including its summary and description.
@ApiResponses: Specifies the possible responses for the operation, including their status codes and descriptions.
@ApiResponse: Used inside @ApiResponses to describe a specific response.
Step 4: Test your REST Service with Swagger
Finally, we can test the REST Service. To do that, reach your Web Context and add the /swagger/dist path at the end of it. For example, in our case with the jaxrs-demo context we will have:
http://localhost:8080/jaxrs-demo/swagger/dist/
And here is your Swagger UI which you can use to test your JAX-RS Service:
As you can see, to change the OpenAPI destination you can use the upper textbox. In our case, the OpenAPI definition is available by default at: http://localhost:8080/jaxrs-demo/rest/openapi.json
Source code: https://github.com/fmarchioni/mastertheboss/tree/master/jax-rs/crud
Conclusion
In this tutorial, we’ve walked through the steps to integrate Swagger UI with WildFly to effectively test and document your RESTful services. By leveraging Swagger UI, you’ve enabled an interactive interface that not only makes your API more accessible to developers and stakeholders but also streamlines the process of testing and debugging your endpoints.
With Swagger UI, you can easily explore your REST services, execute requests directly from the browser, and view detailed responses—all without writing additional client code. This powerful tool enhances the developer experience, facilitates better collaboration, and ensures that your API remains well-documented and easy to use.