Skip to content
Tutorials Center
My learning

Topics

Lesson 15 of 36 ยท REST Endpoints

OpenAPI and Swagger UI

Generate an OpenAPI document and Swagger UI from your Quarkus REST endpoints, enrich it with annotations, serve it in dev mode and use it for client generation.

An API nobody can discover is an API nobody uses. OpenAPI is the standard way to describe a REST API in a machine-readable file: paths, methods, parameters, request and response shapes, error codes. From that file tools produce documentation, test consoles, client libraries and mock servers. Quarkus can generate the file for you from the annotations you already wrote.

The real Quarkus parts are read-only here. The stand-in at the end reads annotations with reflection and prints an OpenAPI-like description, which is the same trick the extension performs at build time.

Turning it on

Add one extension:

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

Now Quarkus scans your resources during the build and serves:

  • /q/openapi the document (YAML by default, ?format=json for JSON),
  • /q/swagger-ui an interactive console (included in dev and test mode, off in production unless you set quarkus.swagger-ui.always-include=true).

In dev mode, open http://localhost:8080/q/swagger-ui. Every endpoint is listed with its parameters, and a Try it out button sends real requests to your running app. Edit a resource, save, reload: the document follows your code.

The generator learns a lot without extra annotations: paths from @Path, verbs from @GET and friends, parameters from @RestPath and @RestQuery, body and response types from method signatures, content types from @Produces and @Consumes, and Bean Validation constraints (such as @Size(max = 120)) become schema limits.

Enriching the document

Add MicroProfile OpenAPI annotations for what the code cannot say:

Java
import org.eclipse.microprofile.openapi.annotations.Operation;
import org.eclipse.microprofile.openapi.annotations.media.Content;
import org.eclipse.microprofile.openapi.annotations.media.Schema;
import org.eclipse.microprofile.openapi.annotations.parameters.Parameter;
import org.eclipse.microprofile.openapi.annotations.responses.APIResponse;
import org.eclipse.microprofile.openapi.annotations.tags.Tag;

@Path("/books")
@Tag(name = "Books", description = "The catalogue")
public class BookResource {

    @GET
    @Path("/{id}")
    @Operation(summary = "Find a book", description = "Returns one book by its database id.")
    @APIResponse(responseCode = "200", description = "The book",
                 content = @Content(schema = @Schema(implementation = BookDto.class)))
    @APIResponse(responseCode = "404", description = "No such book")
    public BookDto one(@Parameter(description = "Book id", example = "42") @RestPath long id) {
        return service.find(id);
    }
}

And describe the DTOs:

Java
@Schema(name = "Book", description = "A book in the catalogue")
public record BookDto(
        @Schema(example = "42", readOnly = true) Long id,
        @Schema(example = "Dune", required = true) String title,
        @Schema(example = "1965") int year) {}

For the API as a whole, use @OpenAPIDefinition on any class, or properties:

PROPERTIES
quarkus.smallrye-openapi.info-title=Bookshop API
quarkus.smallrye-openapi.info-version=1.2.0
quarkus.smallrye-openapi.info-description=Browse and manage the catalogue.
quarkus.swagger-ui.path=/docs
quarkus.smallrye-openapi.store-schema-directory=target/openapi

The last line writes the generated file to disk at build time, handy for committing the contract or feeding a generator.

Security and scopes in the document

If you use JWT or OIDC security, declare the scheme so Swagger UI shows an Authorize button:

Java
@SecurityScheme(securitySchemeName = "jwt", type = SecuritySchemeType.HTTP,
                scheme = "bearer", bearerFormat = "JWT")
public class SecurityConfig {}

@SecurityRequirement(name = "jwt")
@GET @Path("/mine")
public List<BookDto> mine() { ... }

Using the document

Once /q/openapi exists, you can:

  • Generate client code (Java, TypeScript, Python...) with openapi-generator. Quarkus also has quarkus-openapi-generator which creates REST client interfaces from a spec.
  • Publish docs with Redoc or Stoplight, or share the file with front-end teams.
  • Check compatibility in CI: compare the new file with the last released one and fail the build on a breaking change.
  • Generate the document from the spec first (contract-first), then implement the interface. Both directions are valid; choose one per service and stick to it.

Code becomes contract

Code Resources, DTOs, constraints.
Scan The extension reads them at build time.
Document /q/openapi describes the API.
Swagger UI Try every endpoint in the browser.

The document is always in step with the code.

1 / 2

The idea in miniature

This stand-in defines two annotations of its own, reads them from a resource class and prints an OpenAPI-style description. The real extension reads the real Jakarta REST annotations and also analyses Java types for the schemas, but the shape of the work is the same.

Java Stand-in: generate an API description from annotations

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

Swagger UI is great during development. In production, think before exposing it: it lists every endpoint and parameter. Many teams publish the OpenAPI file in a developer portal and leave the console off.

A second look: documenting errors

Error responses are part of the contract. Declare them once with a reusable annotation, or let the exception mappers show up through @APIResponse(responseCode = "409", ...). Clients generated from the spec then know that a 409 can come back and what the body looks like.

Java Stand-in: checking a response against the contract

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which extension generates the OpenAPI document in Quarkus?

    quarkus-smallrye-openapi serves /q/openapi and, in dev and test, the Swagger UI.
  2. 2. Where is the Swagger UI available in dev mode by default?

    The default path is /q/swagger-ui; change it with quarkus.swagger-ui.path.
  3. 3. What does @APIResponse(responseCode = "404") add?

    OpenAPI annotations describe the API. They do not change behaviour.
  4. 4. Which is a good use of the generated OpenAPI file?

    The spec is a machine-readable contract that clients, docs and CI checks can use.

Summary

  • quarkus-smallrye-openapi builds the OpenAPI document at build time and serves it at /q/openapi.
  • Swagger UI (/q/swagger-ui) lets you try endpoints; it is on in dev and test mode.
  • Enrich the document with @Operation, @APIResponse, @Parameter, @Schema, @Tag and security annotations.
  • Use the file for docs, client generation and compatibility checks.

Next: Hibernate ORM with Panache