In this section, you will learn how to generate the RAML file for your JAX-RS application. To generate the RAML file for JAX-RS, we use the jaxrs-to-raml-maven-plugin Maven plugin that comes as a part of RAML for the JAX-RS project (from MuleSoft Inc.). The source for RAML for JAX-RS is available at https://github.com/mulesoft/raml-for-jax-rs.

The jaxrs-to-raml-maven-plugin Maven plugin is capable of identifying the JAX-RS annotation, which you can set on the resource class, resource methods, and fields, and uses this metadata to generate the RAML file while building the source. The jaxrs-to-raml-maven-plugin Maven plugin supports the following set of JAX-RS annotations: @Path, @Consumes, @Produces, @QueryParam, @FormParam, @PathParam, @HeaderParam, @DELETE, @GET, @HEAD, @OPTIONS, @POST, @PUT, and @DefaultValue. The JAXB annotated (@XmlRootElement) classes that appear in the resource method signature will be represented using JSON or XML schemas (depending upon the media type set for the method) in the RAML file.

The steps that you will perform for using JAX-RS to RAML Maven plugin in a JAX-RS application are as follows:

1. The jaxrs-to-raml-maven-plugin Maven plugin is available in the https://repository-master.mulesoft.org/releases/. 
2. Go to the project where you have all JAX-RS resource classes defined, and include jaxrs-raml-maven-plugin in the project's pom.xml file. The <plugin> entry in the pom.xml file will look like the following with the required dependencies:

<build> 
<plugins> 
         <plugin>
                <groupId>org.raml.jaxrs</groupId>
                <artifactId>jaxrs-to-raml-maven-plugin</artifactId>
                <version>2.1.0</version>
                <dependencies>
                    <dependency>
                        <groupId>org.raml.jaxrs</groupId>
                        <artifactId>jaxrs-to-raml-methods</artifactId>
                        <version>2.1.0</version>
                    </dependency>
                    <dependency>
                        <groupId>org.eclipse.persistence</groupId>
                        <artifactId>javax.persistence</artifactId>
                        <version>2.1.0</version>
                    </dependency> 
                </dependencies>
                
                <executions>
                    <execution>
                        <phase>package</phase>
                        <goals>
                            <goal>jaxrstoraml</goal>
                        </goals>
                       <configuration>
                            <baseUrl>http://localhost:28080/rest-chapter7-jaxrs2raml/webresources</baseUrl>
                            <title>department resource</title>
                            <version>1.0</version>
                            <sourceDirectory>${basedir}/src/main/java</sourceDirectory>
                            <outputFile>${project.build.directory}/generated-sources/jaxrs-raml/department-resource.raml</outputFile>
                            <removeOldOutput>true</removeOldOutput>
                        </configuration>
                    </execution>
                </executions>
            </plugin>
    <!-- Other plugin entries go here -->           
</plugins> 
</build> 

You are now done with the setup. When you run mvn compile or mvn package, the jaxrs-raml-maven-plugin plugin that you added in the previous step will generate the RAML file in the Maven's generated-sources folder for all the JAX-RS resource classes found in the Maven source folder.

It is now time for us to see jaxrs-to-raml-maven-plugin in action. The RAML file generated for the DepartmentResource class, which we discussed a while ago in the Generating WADL from JAX-RS section, is shown here. You will also see an annotations folder in the generated source with the Department type object in it. The Department object represents the message entity used in this example:

#%RAML 1.0
title: Raml API generated from rest-chapter7-jaxrs2raml
version: 1.0
baseUri: "http://www.packtpub.com"
mediaType: "*/*"
types:
/departments:
    get:
        responses:
            200:
                body:
                    application/json:
                        type: List
        queryParameters:
            from:
                type: integer
                default: 1
                required: false
            to:
                type: integer
                default: 100
                required: false
    post:
        body:
            type: Department
    /{id}:
        put:
            body:
                type: Department
        get:
            responses:
                200:
                    body:
                        application/json:
                            type: Department