JAX RS to RAML Command Line Interface

The JAX-RS API uses Java programming language annotations to simplify the development of RESTful web services (refer). Java class files contain jax-rs annotation for actions and resources.

Jax-rs make developer to easily develop Rest Service. RAML stands for RESTful API Modeling Language, it encourages user for re-usability, pattern sharing and enable discovery. As you understood Jax-Rs and RAML technologies.  Now its time for conversion from Jax-Rs to RAML.

1. Create a  REST – JAX RS Service for Employee Download service
2. Download  1.0 Final: jsr311-api-1.1.1.jar.
3. Download Command line tool jax-rs-to-raml.jar.
4. Create JAX RSToRAML/service folder, put java files inside this folder. Open command prompt from this folder.
5.   In order to generate your RAML code, you must run it by invoking:: 



        javac [classes]  
         -sourcepath [path-to-your-java-source-code]  
         -classpath [your-classpath]  
         -processorpath [path-to-your-jar]/jax-rs-to-raml.jar  
         -processor com.mulesoft.jaxrs.raml.annotation.model.  
          apt.RAMLAnnotationProcessor  
         -Aramlpath=[path]  
         -implicit:class  


Options::
·       classes: The JAVA classes from which you want to generate a RAML representation.
·       -sourcepath: The folder containing the packages where the classes (and classes' dependencies) are located
·       -classpath: The classpath of the Java project, the classes belong to. 
·       -processorpath: The path to the jar you downloaded (or built).
·       -processor: Indicates the annotation processor. Use:com.mulesoft.jaxrs.raml.annotation.model.apt.RAMLAnnotationProcessor
·       -Aramlpath: The folder which the generated RAML definition will be placed.
·       -imlicit: class specifies that the annotations in the dependent files must also be resolved by the processor.


6. Example::



     javac src/project1/Employee.java src/project1/EmployeeList.java src/project1/EmployeeService.java src/project1/GenericApplication.java   
         -processorpath jax-rs-to-raml.jar   
         -classpath jsr311-api-1.1.1.jar   
         -processor com.mulesoft.jaxrs.raml.annotation.model.apt.RAMLAnnotationProcessor   
         -Aramlpath=RAML   
         -implicit:class  



7. Generated RAML document doesn’t include schema. Steps to make valid RAML document::


•           Convert JSON output into JSON schema (JsonToJsonSchema)               
 JSON Code



                       {  
                           "list" : [  
                                    {  
                                       "id" : 1,  
                                       "name" : "Arnold"  
                                     },  
                                     {  
                                        "id" : 2,  
                                         "name" : "Simon"  
                                       }  
                                  ]  
                          }  



•             Add JSON schema into RAML file.
•        EmployeeService.raml is valid raml document.(RAML Location)
 


References:
https://github.com/mulesoft/raml-for-jax-rs/tree/master/jaxrs-to-raml