How to use Swagger UI in Quarkus

Documentation is a critical part of building APIs, as it helps developers and users understand and interact with your endpoints effectively. Swagger UI is a powerful tool that simplifies this process. In this article, we’ll explore how you can integrate and customize Swagger UI in a Quarkus application with minimal effort.

What is Swagger UI?

Swagger UI is an open-source tool that provides an interactive interface to visualize and test APIs defined by the OpenAPI specification. It transforms your API documentation into a user-friendly interface where users can not only read the endpoint details but also execute test requests directly from the browser. This interactivity makes Swagger UI a popular choice for API developers.

Integrating Swagger UI in Quarkus

Quarkus makes it remarkably easy to set up Swagger UI. By including a single dependency, you can expose your OpenAPI-compliant API documentation in a Swagger UI interface:

<dependency>
    <groupId>io.quarkus</groupId>
    <artifactId>quarkus-smallrye-openapi</artifactId>
</dependency>

Once this dependency is added to your pom.xml file, Quarkus automatically generates OpenAPI documentation for your application and serves it through Swagger UI.

Then, you can access Swagger UI with Quarkus at the following address: http://localhost:8080/q/swagger-ui/

Customizing the Swagger UI Endpoint

By default, Quarkus serves Swagger UI at /q/swagger-ui. However, you can easily change this path to suit your preferences or organizational standards. For instance, to serve the Swagger UI at /swagger, add the following configuration to your application.properties file:

quarkus.smallrye-openapi.path=/swagger

Now, your Swagger UI will be accessible at http://localhost:8080/swagger.

Features of Swagger UI in Quarkus

• Automatic Documentation: With Quarkus and the quarkus-smallrye-openapi dependency, your API endpoints are automatically documented based on annotations like @Path, @GET, @POST, and @Consumes.
• Interactive API Testing: Users can test endpoints by providing parameters and executing requests directly in the browser, making it easier to debug and validate APIs.
• Customization: Apart from changing the UI path, you can further customize the OpenAPI documentation by adding annotations like @Schema and @Operation to enrich your API details.

Conclusion

Using Swagger UI in a Quarkus application is both simple and powerful. By including the quarkus-smallrye-openapi dependency, you can quickly document and test your APIs. Customizing the Swagger UI endpoint ensures it aligns with your application’s requirements. This combination of ease and flexibility makes Swagger UI an essential tool for any Quarkus developer.

With these features in place, your Quarkus application will be well-documented, easier to test, and ready for seamless collaboration with your team and API consumers.