Unlock the Power of Your APIs: A Hands-On Introduction to Quarkus OpenAPI with Swagger

Effortless API Documentation in Quarkus: Getting Started with OpenAPI and Swagger

You're a skilled Java developer, crafting elegant and efficient microservices with the fast Quarkus framework. You've built a fantastic application, maybe something that processes customer orders or even analyzes sensor data. It works perfectly, and you're proud of your creation. But now comes the inevitable question: how do other developers, or even automated systems like AI algorithms, know how to interact with your creation?

This is where the benefit of OpenAPI comes in. Consider it a standard language for describing your application's capabilities. It's like having a detailed blueprint for your service, outlining every available endpoint, the data it expects, and the responses it provides. Without this blueprint, integrating your service with other applications or understanding its functionality becomes a difficult and error-prone process.

In this introduction, we'll explore how Quarkus makes it easy to adopt OpenAPI using the popular Swagger UI. Even if terms like "enterprise requirements" or "API contracts" sound a bit unfamiliar right now, by the end of this article, you'll understand their importance and how they can significantly improve your development workflow, especially when working with AI.

The Difficulty of Undocumented Territory

Let's consider a scenario. Imagine a team of developers working on different parts of a complex system. Your microservice handles user authentication. Another team is building the frontend, and yet another is developing a mobile app. Without clear documentation, the frontend and mobile teams will constantly be asking you questions: "What's the URL for login?", "What data do I need to send?", "What will the response look like?". This leads to wasted time, misunderstandings, and potential integration problems.

Now, consider an AI use case. You've built an API that provides processed data for training a machine learning model. How will the data scientists know the exact format of the data they need to provide to their algorithms? How will an AI-powered chatbot know how to call your service to retrieve specific information? Without a well-defined contract, these integrations become very challenging.

Introducing OpenAPI: Your API's Standard

OpenAPI, formerly known as the Swagger Specification, is an open specification for describing RESTful APIs in a way that is independent of any particular programming language. It allows both humans and machines to understand the capabilities of an API without needing access to source code, additional documentation, or network traffic inspection.

Consider it this way: when you travel to a new country, you often rely on a passport – a standardized document that provides essential information about you. Similarly, OpenAPI acts as a "passport" for your API, providing all the necessary details for others to interact with it easily.

Key benefits of using OpenAPI include:

• Improved Collaboration: It provides a clear and unambiguous agreement for developers, testers, and other stakeholders.

• Automated Tooling: OpenAPI specifications can be used to automatically generate client libraries in various programming languages, API documentation, and even test cases.

• Simplified Integration: It makes it easier for different systems and applications to communicate with each other.

• Enhanced Discoverability: Well-documented APIs are easier to find and understand, encouraging reuse and further development.

• AI-Driven Integrations: For AI use cases, OpenAPI provides a structured way to define the data exchange formats, making it easier for AI models and agents to interact with your services.

Quarkus and OpenAPI: A Good Combination for Developers

Quarkus, with its focus on developer productivity and cloud-native capabilities, provides excellent support for OpenAPI through its extensions. Adding OpenAPI documentation to your Quarkus application is surprisingly simple.

Let's get started and create a basic Quarkus project to see this in action. If you don't have Quarkus set up yet, go to the official Quarkus website and follow the instructions. You’ll be using the Quarkus CLI, so make sure to have it installed.

For this example, we'll create a simple REST endpoint that greets a user.

Step 1: Create a new Quarkus project

Open your terminal and run the following command:

quarkus create app org.acme:openapi-swaggerui-quickstart \
    --extension='resteasy' \
    --no-code
cd openapi-example

Step 2: Add the OpenAPI extension

 quarkus extension add quarkus-smallrye-openapi

Step 3: Create OpenAPIConfig.java

Create a new Java class named OpenAPIConfig.java in the src/main/java directory (within your package structure, e.g., org.acme) with the following content:

package org.acme;

import jakarta.ws.rs.ApplicationPath;
import jakarta.ws.rs.core.Application;
import org.eclipse.microprofile.openapi.annotations.OpenAPIDefinition;
import org.eclipse.microprofile.openapi.annotations.info.Contact;
import org.eclipse.microprofile.openapi.annotations.info.Info;
import org.eclipse.microprofile.openapi.annotations.info.License;
import org.eclipse.microprofile.openapi.annotations.servers.Server;

@ApplicationPath("/api") // You can choose your base path
@OpenAPIDefinition(info = @Info(title = "Greeting API", 
                          version = "1.0.0", 
                          description = "A simple API to greet users", 
                          contact = @Contact(name = "API Support", 
                          url = "http://example.com/support", 
                          email = "support@example.com"), 
                          license = @License(name = "Apache 2.0", 
                                  url = "https://www.apache.org/licenses/LICENSE-2.0.html")), 
                                servers = {
        @Server(url = "http://localhost:8080", description = "Local development server"),
        @Server(url = "https://example.com/api", description = "Production server")
})
public class OpenAPIConfig extends Application {
    // Empty class - the annotations are what matter
}

Step 4: Create a simple REST endpoint (GreetingResource.java)

Create a new Java file named GreetingResource.java in the src/main/java/org/acme directory with the following content:

package org.acme;

import jakarta.ws.rs.GET;
import jakarta.ws.rs.Path;
import jakarta.ws.rs.Produces;
import jakarta.ws.rs.QueryParam;
import jakarta.ws.rs.core.MediaType;
import org.eclipse.microprofile.openapi.annotations.Operation;
import org.eclipse.microprofile.openapi.annotations.parameters.Parameter;

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

    @GET
    @Produces(MediaType.TEXT_PLAIN)
    @Operation(summary = "Greets a user")
    public String hello(
            @Parameter(name = "name", description = "The name of the person to greet") @QueryParam("name") String name) {
        if (name != null && !name.isEmpty()) {
            return "Hello, " + name + "!";
        } else {
            return "Hello!";
        }
    }
}

Step 5: Run the application and explore!

Now, let's run our Quarkus application using the following command in your terminal:

quarkus dev

Quarkus will start in development mode. Once the application is running, open your web browser and navigate to http://localhost:8080/q/openapi.

You should see a JSON document that describes your API. This is the raw OpenAPI specification generated automatically by Quarkus based on your JAX-RS and OpenAPI annotations.

Making it User-Friendly with Swagger UI

While the raw OpenAPI specification is useful for machines, humans often prefer a more visual and interactive way to explore APIs. This is where Swagger UI comes in. Swagger UI is a collection of HTML, CSS, and JavaScript assets that dynamically generate documentation from an OpenAPI specification.

Quarkus makes it easy to integrate Swagger UI into your application. Simply navigate your browser to http://localhost:8080/q/swagger-ui.

You'll be presented with an interactive interface where you can:

• View your API endpoints: See the available paths (/hello in our case).

• Inspect operations: Understand the HTTP methods (GET), parameters (the name query parameter), and response formats.

• Try out your API: Directly interact with your API endpoints by providing parameters and sending requests. You can see the responses in real-time.

This interactive documentation is valuable for developers who need to understand and integrate with your API. They can explore the available endpoints, understand the required inputs, and see example responses without writing code.

Customizing Your OpenAPI Documentation

While Quarkus automatically generates a lot of information, you'll often want to add more details to make your documentation even better. You can achieve this using various annotations from the org.eclipse.microprofile.openapi.annotations package within your OpenAPIConfig.java and on your resource methods. We've already seen examples of @Info, @Contact, @License, @Server, @Operation, and @Parameter. You can explore other annotations to define request bodies, response schemas, security requirements, and much more.

Quarkus Developer UI: Your Central Tool

Quarkus provides a Developer UI, accessible at http://localhost:8080/q/dev, which acts as a central place for various development tools and information. You can easily find the link to the Swagger UI within the Developer UI, making it even more convenient to access your API documentation during development.

OpenAPI and the AI Field

Now, let's consider how OpenAPI is important in the context of Artificial Intelligence. As AI becomes more integrated into our applications, the need for clear and well-defined APIs becomes even more critical.

Here are a few ways OpenAPI can be used in AI use cases:

• Documenting Data APIs for AI Training: If you have an API that provides a stream of processed data used to train a machine learning model, using OpenAPI allows you to precisely define the format of this data, including the data types, units, and any other relevant information. This ensures that the AI model receives the data in the expected format, preventing errors and improving training efficiency.

• Exposing AI Model APIs: Once an AI model is trained and deployed, you'll likely want to expose it through an API so other applications can use its capabilities. For example, an image recognition service might have an API endpoint that accepts an image and returns a list of identified objects. OpenAPI allows you to define the input format (e.g., image file, URL), the expected output (e.g., JSON with object names and confidence scores), and any error codes. This makes it easy for other developers to integrate the AI model into their applications.

• Automating Client Generation for AI Services: Many AI service providers offer OpenAPI specifications for their APIs. Tools can then automatically generate client libraries in various programming languages from these specifications. This simplifies the process of interacting with these AI services, as developers don't need to manually write the code for making API calls and handling responses.

• Standardizing Data Exchange: In complex AI systems involving multiple components, OpenAPI can serve as a standard for defining the data exchange formats between different modules. This promotes interoperability and makes it easier to build and maintain the overall system.

For example, consider a Quarkus application that uses a natural language processing (NLP) AI model to analyze customer reviews. You could have an endpoint that accepts a customer review as input and returns a sentiment score. Using OpenAPI, you can clearly define the input parameter (the review text) and the output format (a JSON object containing the sentiment score and potentially other relevant information). This allows other parts of your system, such as a reporting dashboard, to easily use the output of this AI-powered service.

Conclusion: Embrace the Benefit of OpenAPI

As you've seen, integrating OpenAPI support into your Quarkus applications is quite simple. By adding the quarkus-smallrye-openapi extension and using Jakarta REST and OpenAPI annotations, you can automatically generate documentation for your APIs using Swagger UI.

Understanding and using OpenAPI is an important skill for any modern Java developer, especially in today's environment where microservices and AI-driven applications are becoming increasingly common. It supports better collaboration, simplifies integration, and helps you realize the full potential of your software.

So, the next time you're building a Quarkus application, remember the benefit of OpenAPI. It's not just about generating documentation; it's about creating a clear agreement that allows others (and even intelligent machines) to easily interact with your software. Adopt this standard for your APIs and see the advantages it brings.

Read more about Quarkus and OpenAPI integration:

• This guide explains how your Quarkus application can expose its API description through an OpenAPI specification and how you can test it via a user-friendly UI named Swagger UI.

• SmallRye OpenAPI extension documentation

• Quarkus OpenAPI Generator

• MicroProfile OpenAPI for everyone