Built by Maven

openapi-toolkit:build-docs

Full name:

net.mwalser:openapi-toolkit-maven-plugin:0.2.0:build-docs

Description:

Renders each API description as an HTML reference page with Redoc (redocly build-docs). The page is pre-rendered and self-contained apart from the Redoc script, which it loads from Redocly's CDN, and the Google Fonts stylesheet.

Attributes:

  • Requires a Maven project to be executed.
  • The goal is thread-safe and supports parallel builds.
  • Binds by default to the lifecycle phase: generate-resources.

Optional Parameters

Name Type Since Description
<addResource> boolean - Add the pages as project resources, packaged under their file names at the root of the JAR or under resourceTargetPath. The goal must run before process-resources, which copies resources into the JAR.
Default: false
User Property: openapi.toolkit.buildDocs.addResource
<apis> List<String> - The API descriptions to process: aliases from the apis section of the configuration file, paths relative to the project base directory, or URLs. Empty: every API in the configuration file. Without a configuration file, paths or URLs are required and Redocly's built-in recommended ruleset applies.
User Property: openapi.toolkit.apis
<configFile> File - The Redocly configuration file. Unset: redocly.yaml in the project base directory if it exists, otherwise no configuration file.
User Property: openapi.toolkit.configFile
<disableGoogleFont> boolean - Leave out the link to the Google Fonts stylesheet; the page then renders in the viewer's fallback fonts.
Default: false
User Property: openapi.toolkit.buildDocs.disableGoogleFont
<lintConfig> String - Severity of problems in the configuration file, which is linted before the goal runs: warn (reported, invalid entries are ignored), error (fails the build) or off.
Default: warn
User Property: openapi.toolkit.lintConfig
<maxProblems> int - Maximum number of problems printed to the build log, per API description and for the configuration file. Report files are not limited.
Default: 100
User Property: openapi.toolkit.maxProblems
<outputDirectory> File - Directory the pages are written to, named after the alias (APIs from the configuration file) or the file name (paths), with extension html.
Default: ${project.build.directory}/generated-resources/redoc
User Property: openapi.toolkit.buildDocs.outputDirectory
<outputFile> File - File to write the page to instead of outputDirectory. Requires a single selected API.
User Property: openapi.toolkit.buildDocs.outputFile
<redocOptions> Map<String,String> - Redoc options such as hideDownloadButton or expandResponses. They override the options of the openapi section of the configuration file top-level option by top-level option: a theme given here replaces the configured theme as a whole. Values are strings; nested options such as theme are given as JSON.
<resourceTargetPath> String - Directory inside the JAR for addResource, relative to its root: META-INF/resources for a page that Spring Boot, Quarkus and servlet containers serve as a static file. Unset: the root of the JAR.
User Property: openapi.toolkit.buildDocs.resourceTargetPath
<skip> boolean - Skip execution. As the property openapi.toolkit.skip it skips every goal of the plugin; the goal-specific properties such as openapi.toolkit.lint.skip skip one goal.
Default: false
User Property: openapi.toolkit.skip
<skipBuildDocs> boolean - Skip this goal only; openapi.toolkit.skip skips every goal of the plugin.
Default: false
User Property: openapi.toolkit.buildDocs.skip
<template> File - Handlebars template of the page instead of the built-in one (or instead of htmlTemplate from the openapi section of the configuration file). It receives title, redocHead and redocHTML (both to be inserted unescaped, with triple braces), disableGoogleFont for the template's own font link, and templateOptions.
User Property: openapi.toolkit.buildDocs.template
<templateOptions> Map<String,String> - Values for a custom template, available there as templateOptions.name.
<title> String - Title of the pages; with several APIs they all get it. Unset: the title of each API description.
User Property: openapi.toolkit.buildDocs.title

Parameter Details

<addResource>

Add the pages as project resources, packaged under their file names at the root of the JAR or under resourceTargetPath. The goal must run before process-resources, which copies resources into the JAR.
  • Type: boolean
  • Required: No
  • User Property: openapi.toolkit.buildDocs.addResource
  • Default: false

<apis>

The API descriptions to process: aliases from the apis section of the configuration file, paths relative to the project base directory, or URLs. Empty: every API in the configuration file. Without a configuration file, paths or URLs are required and Redocly's built-in recommended ruleset applies.
  • Type: java.util.List<java.lang.String>
  • Required: No
  • User Property: openapi.toolkit.apis

<configFile>

The Redocly configuration file. Unset: redocly.yaml in the project base directory if it exists, otherwise no configuration file.
  • Type: java.io.File
  • Required: No
  • User Property: openapi.toolkit.configFile

<disableGoogleFont>

Leave out the link to the Google Fonts stylesheet; the page then renders in the viewer's fallback fonts.
  • Type: boolean
  • Required: No
  • User Property: openapi.toolkit.buildDocs.disableGoogleFont
  • Default: false

<lintConfig>

Severity of problems in the configuration file, which is linted before the goal runs: warn (reported, invalid entries are ignored), error (fails the build) or off.
  • Type: java.lang.String
  • Required: No
  • User Property: openapi.toolkit.lintConfig
  • Default: warn

<maxProblems>

Maximum number of problems printed to the build log, per API description and for the configuration file. Report files are not limited.
  • Type: int
  • Required: No
  • User Property: openapi.toolkit.maxProblems
  • Default: 100

<outputDirectory>

Directory the pages are written to, named after the alias (APIs from the configuration file) or the file name (paths), with extension html.
  • Type: java.io.File
  • Required: No
  • User Property: openapi.toolkit.buildDocs.outputDirectory
  • Default: ${project.build.directory}/generated-resources/redoc

<outputFile>

File to write the page to instead of outputDirectory. Requires a single selected API.
  • Type: java.io.File
  • Required: No
  • User Property: openapi.toolkit.buildDocs.outputFile

<redocOptions>

Redoc options such as hideDownloadButton or expandResponses. They override the options of the openapi section of the configuration file top-level option by top-level option: a theme given here replaces the configured theme as a whole. Values are strings; nested options such as theme are given as JSON.
  • Type: java.util.Map<java.lang.String, java.lang.String>
  • Required: No

<resourceTargetPath>

Directory inside the JAR for addResource, relative to its root: META-INF/resources for a page that Spring Boot, Quarkus and servlet containers serve as a static file. Unset: the root of the JAR.
  • Type: java.lang.String
  • Required: No
  • User Property: openapi.toolkit.buildDocs.resourceTargetPath

<skip>

Skip execution. As the property openapi.toolkit.skip it skips every goal of the plugin; the goal-specific properties such as openapi.toolkit.lint.skip skip one goal.
  • Type: boolean
  • Required: No
  • User Property: openapi.toolkit.skip
  • Default: false

<skipBuildDocs>

Skip this goal only; openapi.toolkit.skip skips every goal of the plugin.
  • Type: boolean
  • Required: No
  • User Property: openapi.toolkit.buildDocs.skip
  • Default: false

<template>

Handlebars template of the page instead of the built-in one (or instead of htmlTemplate from the openapi section of the configuration file). It receives title, redocHead and redocHTML (both to be inserted unescaped, with triple braces), disableGoogleFont for the template's own font link, and templateOptions.
  • Type: java.io.File
  • Required: No
  • User Property: openapi.toolkit.buildDocs.template

<templateOptions>

Values for a custom template, available there as templateOptions.name.
  • Type: java.util.Map<java.lang.String, java.lang.String>
  • Required: No

<title>

Title of the pages; with several APIs they all get it. Unset: the title of each API description.
  • Type: java.lang.String
  • Required: No
  • User Property: openapi.toolkit.buildDocs.title