An OpenAPI specification is a machine-readable description of an HTTP API. In Quarkus, the quarkus-smallrye-openapi extension generates the document from REST resources according to the MicroProfile OpenAPI specification. section 4.10 section 4.2.3
A generated document can describe:
- Service metadata such as its title and version. section 4.2.3
- REST paths and operations, including request bodies, response codes, media types, and schemas. section 4.2.3
- JSON representations linked to application classes through component schema references. section 4.2.3
Swagger UI provides a graphical view of the specification and lets developers execute the documented operations in a browser. Quarkus exposes the document at /q/openapi and the UI at /q/swagger-ui. section 4.2.3
Reservation service
A generated document can describe POST /reservation as accepting and returning application/json, with both payloads represented by a Reservation schema. The same interface can expose GET /reservation/availability for checking available cars. section 4.2.3
Listing 4.9 The OpenAPI document of the Reservation service
---
openapi: 3.0.3
info:
title: reservation-service API
version: 1.0.0-SNAPSHOT
paths:
/reservation:
post:
tags:
- Reservation Resource
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/Reservation'
responses:
"200":
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/Reservation'
Inspect the generated OpenAPI document to see service metadata, paths, HTTP operations, JSON content types, responses, and schema references. section 4.2.3
Swagger UI is included by default in Dev mode. Production deployments require quarkus.swagger-ui.always-include=true when the interactive UI should remain available; document customization is possible but deferred. section 4.2.3
