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.
Features
Specify 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=trueYou 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.yamlYou 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
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.0.1</version>
</dependency>Usage
Once installed, Redoc will be available at /q/redoc in dev and test modes. Simply navigate to that URL to view your API documentation.
Extension Configuration Reference
Configuration property fixed at build time - All other configuration properties are overridable at runtime
Configuration property |
Type |
Default |
|---|---|---|
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: |
string |
|
The title displayed in the browser tab. Environment variable: |
string |
|
If true, Redoc is included in production builds. By default, Redoc is only available in dev and test modes. Environment variable: |
boolean |
|
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: |
boolean |
|
Hides the schema title next to the type. Environment variable: |
boolean |
|
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: |
string |
|
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: |
int |
|
Controls how API documentation panels are displayed on the page.
Environment variable: |
|
|
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: |
boolean |
|
Shows required properties in schemas first, ordered in the same order as in the required array. Environment variable: |
boolean |
|
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: |
string |
|
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: |
int |
|
Shows specification extensions ('x-' fields). Extensions used by Redoc are ignored. The value can be:
Environment variable: |
string |
|
If set to true, the spec is considered untrusted and all HTML/Markdown is sanitized. Environment variable: |
boolean |
|
The title/label for this download option (e.g., "YAML", "JSON"). Environment variable: |
string |
required |
The URL to download the API definition from. Environment variable: |
string |
required |
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: |
string |
|
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: |
int |
|
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: |
boolean |
|
A list of schema names to ignore. Matching schemas are excluded from the documentation. Multiple schema names can be specified. Environment variable: |
list of string |
|
Hides the loading animation. Environment variable: |
boolean |
|
Hides the sidebar navigation menu. Environment variable: |
boolean |
|
Whether Redoc is enabled at runtime. If false, the Redoc UI will return a 404 response. Environment variable: |
boolean |
|