Maven RADL Plugin

Using the RADL Maven Plugin

The RADL Maven plugin is available from Bintray's jCenter:

<build>
    <plugins>
        <plugin>
            <groupId>radl</groupId>
            <artifactId>radl-maven</artifactId>
            <version>${radl-maven.version}</version>
            <executions>
                <execution>
                    <id>process-radl</id>
                    <goals>
                        <goal>...</goal>
                    </goals>
                </execution>
            </executions>
        </plugin>
    </plugins>
</build>
<pluginRepositories>
    <pluginRepository>
         <id>bintray-radl</id>
        <name>BinTray Maven Repository</name>
        <url>http://dl.bintray.com/radl/RADL/</url>
    </pluginRepository>
</pluginRepositories>

You can either hard-code the version of the plugin, or follow the above example an add a property to 'radl-maven.plugin.version':

radl-maven.version=1.0.5

Maven Tasks

The plugin adds the following tasks to your build:

• validateRadl validates RADL files against the schema and against additional guidelines
• radl2docs transforms RADL files into HTML-based documentation
• radl2spring generates Spring server source code from RADL files
• radlFromCode extracts RADL from Spring based or JAX-RS based REST server source code

See the following sections for more detail.

Validating RADL Descriptions

See Validating RADL Descriptions for an overview of the process.

Goal

• validateRadl

Available configuration parameters

• radlDirName
• serviceName
• failOnValidationErrors
• issueFile

Sample usages

<plugin>
    <groupId>radl</groupId>
    <artifactId>radl-maven</artifactId>
    <version>${radl-maven.plugin.version}</version>
    <executions>
        <execution>
            <id>process-radl</id>
            <goals>
                <goal>validateRadl</goal>
            </goals>
        </execution>
        <configuration>
            <!-- optionally, configure below parameters; sets to default in below samples -->
            <!--
            <radlDirName>${project.build.directory}/radl</radlDirName>
            <serviceName>${project.name}</serviceName>
            <failOnValidationErrors>true</failOnValidationErrors>
            <issueFile>${project.build.directory}/radl/radl-issues.xml</issueFile>
            -->
        </configuration>
    </executions>
</plugin>

Generating Documentation

See Generating Documentation for an overview of the process.

Goal

• radl2docs

Available configuration parameters

• radlDirName
• cssURL
• serviceName
• docsDir

Sample Usage

<plugin>
    <groupId>radl</groupId>
    <artifactId>radl-maven</artifactId>
    <version>${radl-maven.plugin.version}</version>
    <executions>
        <execution>
            <id>process-radl</id>
            <goals>
                <goal>radl2docs</goal>
            </goals>
        </execution>
        <configuration>
            <!-- optionally, configure below parameters; sets to default in below samples -->
            <!--
            <radlDirName>${project.build.directory}/radl</radlDirName>
            <serviceName>${project.name}</serviceName>
            <docsDir>${project.build.directory}/radl</docsDir>
            <cssURL>file:///local-radl-css-file.css</cssURL>
            -->
        </configuration>
    </executions>
</plugin>

Generating Java Code From RADL

See Generating Java Code From RADL for an overview of the process.

Goal

• radl2spring

Available configuration parameters

• radlDirName
• serviceName
• baseDir
• packagePrefix
• relativeGeneratedSourceDir
• relativeGeneratedManualSourceDir
• scm

Sample Usage

<plugin>
    <groupId>radl</groupId>
    <artifactId>radl-maven</artifactId>
    <version>${radl-maven.plugin.version}</version>
    <executions>
        <execution>
            <id>process-radl</id>
            <goals>
                <goal>radl2spring</goal>
            </goals>
        </execution>
        <configuration>
            <!-- optionally, configure below parameters; sets to default in below samples -->
            <!--
            <radlDirName>${project.build.directory}/radl</radlDirName>
            <serviceName>${project.name}</serviceName>
            <baseDir>${basedir}</baseDir>
            <packagePrefix>radl.sample.rest.server</packagePrefix>
            <relativeGeneratedSourceDir>${project.build.directory}/generated-src/java</relativeGeneratedSourceDir>
            <relativeGeneratedManualSourceDir>${project.build.directory}/generated-src/manual</relativeGeneratedManualSourceDir>
            <scm>default</scm>
            -->
        </configuration>
    </executions>
</plugin>

Extracting RADL From Java Code

See Extracting RADL from Java code for an overview of the process.

Goal

• radlFromCode

Available configuration parameters

• serviceName
• srcDir
• docsDir
• classpathScope
• configurationFile
• argumentFile

Sample Usage

<plugin>
    <groupId>radl</groupId>
    <artifactId>radl-maven</artifactId>
    <version>${radl-maven.plugin.version}</version>
    <executions>
        <execution>
            <id>process-radl</id>
            <goals>
                <goal>radlFromCode</goal>
            </goals>
        </execution>
        <configuration>
            <!-- optionally, configure below parameters; sets to default in below samples -->
            <!--
            <serviceName>${project.name}</serviceName>
            <baseDir>${basedir}/src/main/java</baseDir>
            <docsDir>${project.build.directory}/radl</docsDir>
            <classpathScope>runtime</classpathScope>
            -->
        </configuration>
    </executions>
</plugin>

Configuration

The plugin adds the radl project extension to your Maven project with the following properties:

• radlDirName Location of RADL files. Defaults to src/main/radl.
• serviceName The name of the service that the RADL files describe. Defaults to the project's name.
• docsDir The sub-directory of the project build directory into which documentation is generated. Defaults to target/radl.
• cssURL One optional css URL to customize the documentation. Defaults to RADL's default css.
• issueFile The output issue file reported by the validation. Defaults to target/radl/radl-issues.xml.
• failOnValidationErrors Specifying whether to fail on receiving validation errors or ignore errors. Defaults to true, which means to fail on errors.
• baseDir The base project directory to look up sources. Defaults to project's root directory.
• packagePrefix The prefix to use when generating Java packages. Defaults to radl.sample.rest.server.
• relativeGeneratedSourceDir The relative directory path where the generated source codes are put. This set of codes do not need further manual work.
• relativeGeneratedManualSourceDir The relative directory path where the generated source codes are put. This set of codes need further manual work.
• scm The source code management system to use. Defaults to default. The only other valid value is p4 for Perforce.
• classpathScope The classpath scope which is used for the compilation of the RADL extraction from code. Available values are: runtime, compile, test and system. Defaults to runtime.
• argumentFile The argument properties file specified for the RADL extraction from Java code. When the configuration file is set, other parameters in the maven plugin configuration are merged. See Extracting RADL from Java code for the details.
• configurationFile The configuration properties file specified for the RADL extraction from Java code. See Extracting RADL from Java code for the details.