Quarkus Redoc

This extension provides Redoc API documentation for your Quarkus application. Redoc is an open source tool for generating documentation from OpenAPI (formerly Swagger) definitions.

This extension uses Redoc 3.0 and supports all Redoc Community Edition (CE) configuration options.

Installation

If you want to use this extension, you need to add the io.quarkiverse.redoc:quarkus-redoc extension first to your build file.

For instance, with Maven, add the following dependency to your POM file:

<dependency>
    <groupId>io.quarkiverse.redoc</groupId>
    <artifactId>quarkus-redoc</artifactId>
    <version>0.2.0</version>
</dependency>

Usage

Once installed, Redoc CE will be available at /q/redoc in dev and test modes. Simply navigate to that URL to view your API documentation - or press on the corresponding link in dev-ui.

Swagger UI is Disabled by Default

When you use this extension with quarkus-smallrye-openapi, Swagger UI is automatically disabled to avoid having two API documentation UIs. This extension sets quarkus.swagger-ui.enabled=false by default.

If you want to use both Redoc and Swagger UI, you can explicitly re-enable Swagger UI:

quarkus.swagger-ui.enabled=true

Changing the Download URLs

By default, this extension configures Redoc CE to show download URLs for the OpenAPI document in both JSON and YAML format.

You can disable them completely using the following configuration.

quarkus.redoc.hide-download-buttons=true

You can also override the default provided download URLs with your own. For example, if your API is about users, you could change the URLs as follows.

quarkus.redoc.download-urls[0].title=User API JSON
quarkus.redoc.download-urls[0].url=/q/openapi.json
quarkus.redoc.download-urls[1].title=User API YAML
quarkus.redoc.download-urls[1].url=/q/openapi.yaml

You can provide as many download URLs as you want. See also how to configure indexed properties in the Quarkus documentation: https://quarkus.io/guides/config-reference#indexed-properties

Logo

Your custom logo can be displayed above the sidebar. See the configuration values starting with quarkus.redoc.extensions.x-logo. for more information.

This works by customizing the OpenAPI document generated by quarkus-smallrye-openapi. An additional x-logo vendor extension - from Redoc CE - is added to the info object.

Tag Groups

Often, as applications grow large, so does the amount of OpenAPI tags. OpenAPI tags are used to sort operations into categories.

Tag groups, a Redocly CE feature, allows you to group tags of the same kind together.

Let’s imagine your application has the tags: Order, Order Import, Masterdata, User, User Import

We can configure our application to group these tags as follows.

quarkus.redoc.extensions.x-tag-groups[0].name=Order Management
quarkus.redoc.extensions.x-tag-groups[0].tags=Order, Order Import
quarkus.redoc.extensions.x-tag-groups[1].name=User Management
quarkus.redoc.extensions.x-tag-groups[1].tags=User, User Import

This configuration generates the following groups:

* Order Management
** Order
** Order Import
* User Management
** User
** User Import
* Other
** Masterdata (1)
** Schemas (2)

1	Notice how we did not specify a tag group for Masterdata? Every tag which is not assigned to a category is automatically put into a group called "Other". You can change the name of this group using: `quarkus.redoc.extensions.x-tag-groups-ungrouped-name=Anything else`
2	The `Schemas` tag comes from the `quarkus.redoc.schema-definitions-tag-name` configuration property, and is also put into the `Other` group. You can explicitly assign this tag to another group using the previously shown `quarkus.redoc.extensions.x-tag-groups.tags` option.

Extension Configuration Reference

Configuration property fixed at build time - All other configuration properties are overridable at runtime

Configuration property	Type	Default
`quarkus.redoc.path` The path where Redoc UI is served (relative to non-application root path). The default is "redoc", which means Redoc will be available at /q/redoc. Environment variable: `QUARKUS_REDOC_PATH`	string	`redoc`
`quarkus.redoc.routing-base-path` The base path of Redocly, combined with any other preceding path. Redocly performs URL manipulation when navigating to OpenAPI tags using the sidebar. Useful if this Quarkus application is served behind a reverse proxy which performs URL rewriting. E.g. If the reverse proxy rewrites / to /my-application, and the path config property is `redoc`, then this routing-base-path property should be set to `/my-application/q/redoc`. Environment variable: `QUARKUS_REDOC_ROUTING_BASE_PATH`	string	`Defaults to the resolved path (e.g., /q/redoc)`
`quarkus.redoc.title` The title displayed in the browser tab. Environment variable: `QUARKUS_REDOC_TITLE`	string	`API Documentation`
`quarkus.redoc.always-include` If true, Redoc is included in production builds. By default, Redoc is only available in dev and test modes. Environment variable: `QUARKUS_REDOC_ALWAYS_INCLUDE`	boolean	`false`
`quarkus.redoc.hide-download-buttons` Hides the 'Download' button for saving the API definition source file. This setting does not make the API definition private; it just hides the button. Environment variable: `QUARKUS_REDOC_HIDE_DOWNLOAD_BUTTONS`	boolean	`false`
`quarkus.redoc.hide-schema-titles` Hides the schema title next to the type. Environment variable: `QUARKUS_REDOC_HIDE_SCHEMA_TITLES`	boolean	`false`
`quarkus.redoc.json-samples-expand-level` Sets the default expand level for JSON payload samples (response and request body). The default value is 2, and the maximum supported value is '+Infinity'. It can also be configured as a string with the special value all that expands all levels. Environment variable: `QUARKUS_REDOC_JSON_SAMPLES_EXPAND_LEVEL`	string	`2`
`quarkus.redoc.max-displayed-enum-values` Displays only the specified number of enum values. The remaining values are hidden in an expandable area. By default 10 values are displayed which is ideal for usability. Environment variable: `QUARKUS_REDOC_MAX_DISPLAYED_ENUM_VALUES`	int	`10`
`quarkus.redoc.layout` Controls how API documentation panels are displayed on the page. `three-panel` - Standard layout with sidebar on the left, main content in the center, and code samples on the right `stacked` - Alternative layout that integrates the right panel into the middle panel, creating a single-column view. Better for narrower viewports or sequential reading Environment variable: `QUARKUS_REDOC_LAYOUT`	`three-panel`, `stacked`	`three-panel`
`quarkus.redoc.only-required-in-samples` Shows only required fields in request samples. Use this option if you have a large number of optional fields that can make request samples difficult to read. Environment variable: `QUARKUS_REDOC_ONLY_REQUIRED_IN_SAMPLES`	boolean	`false`
`quarkus.redoc.sort-required-props-first` Shows required properties in schemas first, ordered in the same order as in the required array. Environment variable: `QUARKUS_REDOC_SORT_REQUIRED_PROPS_FIRST`	boolean	`false`
`quarkus.redoc.schemas-expansion-level` Specifies whether to automatically expand schemas in Reference docs. Set it to all to expand all schemas regardless of their level, or set it to a number to expand schemas up to the specified level. For example, schemasExpansionLevel: 3 expands schemas up to three levels deep. Environment variable: `QUARKUS_REDOC_SCHEMAS_EXPANSION_LEVEL`	string	`4`
`quarkus.redoc.scroll-y-offset` Specifies a vertical scroll-offset in pixels. This setting is useful when there are fixed positioned elements at the top of the page, such as navbars, headers, etc. Environment variable: `QUARKUS_REDOC_SCROLL_Y_OFFSET`	int
`quarkus.redoc.show-extensions` Shows specification extensions ('x-' fields). Extensions used by Redoc are ignored. The value can be: `true` - show all specification extensions `false` - hide all specification extensions (default) a comma-separated list of extension names to display (e.g., `x-logo,x-code-samples`) Environment variable: `QUARKUS_REDOC_SHOW_EXTENSIONS`	string	`false`
`quarkus.redoc.sanitize` If set to true, the spec is considered untrusted and all HTML/Markdown is sanitized. Environment variable: `QUARKUS_REDOC_SANITIZE`	boolean	`false`
`quarkus.redoc.download-urls.title` The title/label for this download option (e.g., "YAML", "JSON"). Environment variable: `QUARKUS_REDOC_DOWNLOAD_URLS_TITLE`	string	required
`quarkus.redoc.download-urls.url` The URL to download the API definition from. Environment variable: `QUARKUS_REDOC_DOWNLOAD_URLS_URL`	string	required
`quarkus.redoc.schema-definitions-tag-name` If a value is set, all of the schemas are rendered with the designated tag name. The schemas then render and display in the sidebar navigation (with that associated tag name). Environment variable: `QUARKUS_REDOC_SCHEMA_DEFINITIONS_TAG_NAME`	string	`Schemas`
`quarkus.redoc.generated-samples-max-depth` The generatedSamplesMaxDepth option controls how many schema levels automatically generated for payload samples. The default is 8 which works well for most APIs, but you can adjust it if necessary for your use case. Environment variable: `QUARKUS_REDOC_GENERATED_SAMPLES_MAX_DEPTH`	int	`8`
`quarkus.redoc.hide-properties-prefix` In complex data structures or object schemas where properties are nested within parent objects the hidePropertiesPrefix option enables the hiding of parent names for nested properties within the documentation. Environment variable: `QUARKUS_REDOC_HIDE_PROPERTIES_PREFIX`	boolean	`false`
`quarkus.redoc.ignore-named-schemas` A list of schema names to ignore. Matching schemas are excluded from the documentation. Multiple schema names can be specified. Environment variable: `QUARKUS_REDOC_IGNORE_NAMED_SCHEMAS`	list of string
`quarkus.redoc.hide-loading` Hides the loading animation. Environment variable: `QUARKUS_REDOC_HIDE_LOADING`	boolean	`false`
`quarkus.redoc.hide-sidebar` Hides the sidebar navigation menu. Environment variable: `QUARKUS_REDOC_HIDE_SIDEBAR`	boolean	`false`
`quarkus.redoc.extensions.x-logo.url` The URL to the logo image. This can be: An absolute URL (e.g., https://example.com/logo.png). It SHOULD be an absolute URL so your API definition is usable from any location. A relative path that will have to be served by the application Environment variable: `QUARKUS_REDOC_EXTENSIONS_X_LOGO_URL`	string	required
`quarkus.redoc.extensions.x-logo.background-color` Optional background color for the logo area in hexadecimal format, e.g., #FFFFFF. Environment variable: `QUARKUS_REDOC_EXTENSIONS_X_LOGO_BACKGROUND_COLOR`	string
`quarkus.redoc.extensions.x-logo.alt-text` Optional text to use for the alt HTML tag on the logo image. Environment variable: `QUARKUS_REDOC_EXTENSIONS_X_LOGO_ALT_TEXT`	string	`logo`
`quarkus.redoc.extensions.x-logo.href` Optional URL pointing to the contact page. Environment variable: `QUARKUS_REDOC_EXTENSIONS_X_LOGO_HREF`	string	`Defaults to 'info.contact.url' field from the OpenAPI definition.`
`quarkus.redoc.extensions.x-tag-groups.name` The name of the tag group displayed in the sidebar. Environment variable: `QUARKUS_REDOC_EXTENSIONS_X_TAG_GROUPS_NAME`	string	required
`quarkus.redoc.extensions.x-tag-groups.tags` The list of tag names to include in this group. Environment variable: `QUARKUS_REDOC_EXTENSIONS_X_TAG_GROUPS_TAGS`	list of string	required
`quarkus.redoc.extensions.x-tag-groups-ungrouped-name` Name for the group that contains any tags not explicitly assigned to a tag group. When x-tag-groups is configured, tags not assigned to any group are hidden by Redoc. This option creates an additional group containing all ungrouped tags. Set to an empty string - or null depending on your config source - to disable this group. Environment variable: `QUARKUS_REDOC_EXTENSIONS_X_TAG_GROUPS_UNGROUPED_NAME`	string	`Other`
`quarkus.redoc.enabled` Whether Redoc is enabled at runtime. If false, the Redoc UI will return a 404 response. Environment variable: `QUARKUS_REDOC_ENABLED`	boolean	`true`

Configuration property

Type

Default

quarkus.redoc.path

The path where Redoc UI is served (relative to non-application root path). The default is "redoc", which means Redoc will be available at /q/redoc.

Environment variable: QUARKUS_REDOC_PATH

string

redoc

quarkus.redoc.routing-base-path

The base path of Redocly, combined with any other preceding path. Redocly performs URL manipulation when navigating to OpenAPI tags using the sidebar.

Useful if this Quarkus application is served behind a reverse proxy which performs URL rewriting.

E.g. If the reverse proxy rewrites / to /my-application, and the path config property is redoc, then this routing-base-path property should be set to /my-application/q/redoc.

Environment variable: QUARKUS_REDOC_ROUTING_BASE_PATH

string

Defaults to the resolved path (e.g., /q/redoc)

quarkus.redoc.title

The title displayed in the browser tab.

Environment variable: QUARKUS_REDOC_TITLE

string

API Documentation

quarkus.redoc.always-include

If true, Redoc is included in production builds. By default, Redoc is only available in dev and test modes.

Environment variable: QUARKUS_REDOC_ALWAYS_INCLUDE

boolean

false

quarkus.redoc.hide-download-buttons

Hides the 'Download' button for saving the API definition source file. This setting does not make the API definition private; it just hides the button.

Environment variable: QUARKUS_REDOC_HIDE_DOWNLOAD_BUTTONS

boolean

false

quarkus.redoc.hide-schema-titles

Hides the schema title next to the type.

Environment variable: QUARKUS_REDOC_HIDE_SCHEMA_TITLES

boolean

false

quarkus.redoc.json-samples-expand-level

Sets the default expand level for JSON payload samples (response and request body). The default value is 2, and the maximum supported value is '+Infinity'. It can also be configured as a string with the special value all that expands all levels.

Environment variable: QUARKUS_REDOC_JSON_SAMPLES_EXPAND_LEVEL

string

2

quarkus.redoc.max-displayed-enum-values

Displays only the specified number of enum values. The remaining values are hidden in an expandable area. By default 10 values are displayed which is ideal for usability.

Environment variable: QUARKUS_REDOC_MAX_DISPLAYED_ENUM_VALUES

int

10

quarkus.redoc.layout

Controls how API documentation panels are displayed on the page.

three-panel - Standard layout with sidebar on the left, main content in the center, and code samples on the right
stacked - Alternative layout that integrates the right panel into the middle panel, creating a single-column view. Better for narrower viewports or sequential reading

Environment variable: QUARKUS_REDOC_LAYOUT

three-panel, stacked

three-panel

quarkus.redoc.only-required-in-samples

Shows only required fields in request samples. Use this option if you have a large number of optional fields that can make request samples difficult to read.

Environment variable: QUARKUS_REDOC_ONLY_REQUIRED_IN_SAMPLES

boolean

false

quarkus.redoc.sort-required-props-first

Shows required properties in schemas first, ordered in the same order as in the required array.

Environment variable: QUARKUS_REDOC_SORT_REQUIRED_PROPS_FIRST

boolean

false

quarkus.redoc.schemas-expansion-level

Specifies whether to automatically expand schemas in Reference docs. Set it to all to expand all schemas regardless of their level, or set it to a number to expand schemas up to the specified level. For example, schemasExpansionLevel: 3 expands schemas up to three levels deep.

Environment variable: QUARKUS_REDOC_SCHEMAS_EXPANSION_LEVEL

string

4

quarkus.redoc.scroll-y-offset

Specifies a vertical scroll-offset in pixels. This setting is useful when there are fixed positioned elements at the top of the page, such as navbars, headers, etc.

Environment variable: QUARKUS_REDOC_SCROLL_Y_OFFSET

int

quarkus.redoc.show-extensions

Shows specification extensions ('x-' fields). Extensions used by Redoc are ignored.

The value can be:

true - show all specification extensions
false - hide all specification extensions (default)
a comma-separated list of extension names to display (e.g., x-logo,x-code-samples)

Environment variable: QUARKUS_REDOC_SHOW_EXTENSIONS

string

false

quarkus.redoc.sanitize

If set to true, the spec is considered untrusted and all HTML/Markdown is sanitized.

Environment variable: QUARKUS_REDOC_SANITIZE

boolean

false

quarkus.redoc.download-urls.title

The title/label for this download option (e.g., "YAML", "JSON").

Environment variable: QUARKUS_REDOC_DOWNLOAD_URLS_TITLE

string

required

quarkus.redoc.download-urls.url

The URL to download the API definition from.

Environment variable: QUARKUS_REDOC_DOWNLOAD_URLS_URL

string

required

quarkus.redoc.schema-definitions-tag-name

If a value is set, all of the schemas are rendered with the designated tag name. The schemas then render and display in the sidebar navigation (with that associated tag name).

Environment variable: QUARKUS_REDOC_SCHEMA_DEFINITIONS_TAG_NAME

string

Schemas

quarkus.redoc.generated-samples-max-depth

The generatedSamplesMaxDepth option controls how many schema levels automatically generated for payload samples. The default is 8 which works well for most APIs, but you can adjust it if necessary for your use case.

Environment variable: QUARKUS_REDOC_GENERATED_SAMPLES_MAX_DEPTH

int

8

quarkus.redoc.hide-properties-prefix

In complex data structures or object schemas where properties are nested within parent objects the hidePropertiesPrefix option enables the hiding of parent names for nested properties within the documentation.

Environment variable: QUARKUS_REDOC_HIDE_PROPERTIES_PREFIX

boolean

false

quarkus.redoc.ignore-named-schemas

A list of schema names to ignore. Matching schemas are excluded from the documentation. Multiple schema names can be specified.

Environment variable: QUARKUS_REDOC_IGNORE_NAMED_SCHEMAS

list of string

quarkus.redoc.hide-loading

Hides the loading animation.

Environment variable: QUARKUS_REDOC_HIDE_LOADING

boolean

false

quarkus.redoc.hide-sidebar

Hides the sidebar navigation menu.

Environment variable: QUARKUS_REDOC_HIDE_SIDEBAR

boolean

false

quarkus.redoc.extensions.x-logo.url

The URL to the logo image. This can be:

An absolute URL (e.g., https://example.com/logo.png). It SHOULD be an absolute URL so your API definition is usable from any location.
A relative path that will have to be served by the application

Environment variable: QUARKUS_REDOC_EXTENSIONS_X_LOGO_URL

string

required

quarkus.redoc.extensions.x-logo.background-color

Optional background color for the logo area in hexadecimal format, e.g., #FFFFFF.

Environment variable: QUARKUS_REDOC_EXTENSIONS_X_LOGO_BACKGROUND_COLOR

string

quarkus.redoc.extensions.x-logo.alt-text

Optional text to use for the alt HTML tag on the logo image.

Environment variable: QUARKUS_REDOC_EXTENSIONS_X_LOGO_ALT_TEXT

string

logo

quarkus.redoc.extensions.x-logo.href

Optional URL pointing to the contact page.

Environment variable: QUARKUS_REDOC_EXTENSIONS_X_LOGO_HREF

string

Defaults to 'info.contact.url' field from the OpenAPI definition.

quarkus.redoc.extensions.x-tag-groups.name

The name of the tag group displayed in the sidebar.

Environment variable: QUARKUS_REDOC_EXTENSIONS_X_TAG_GROUPS_NAME

string

required

quarkus.redoc.extensions.x-tag-groups.tags

The list of tag names to include in this group.

Environment variable: QUARKUS_REDOC_EXTENSIONS_X_TAG_GROUPS_TAGS

list of string

required

quarkus.redoc.extensions.x-tag-groups-ungrouped-name

Name for the group that contains any tags not explicitly assigned to a tag group.

When x-tag-groups is configured, tags not assigned to any group are hidden by Redoc. This option creates an additional group containing all ungrouped tags. Set to an empty string - or null depending on your config source - to disable this group.

Environment variable: QUARKUS_REDOC_EXTENSIONS_X_TAG_GROUPS_UNGROUPED_NAME

string

Other

quarkus.redoc.enabled

Whether Redoc is enabled at runtime. If false, the Redoc UI will return a 404 response.

Environment variable: QUARKUS_REDOC_ENABLED

boolean

true