Jax-rs to raml - what types to expect in .raml?


#1

I am using the tool to generate the .raml file from jax-rs.
The generated file contains the type definitions for the classes that I want, but it also contains empty definitions for java classes such as:

int[]:
    properties:
Date:
    properties:
char[]:
    properties:
char:
    properties:
Map:
    properties:

Are these definition necessary to use the .raml to automatically generate the documentation and the console application to test the API ?
If not, I can I select what types to have in the generated .raml file ?

It would be too complex to share the real project and so I created a new one where I can replicate the same results.

pom.xml:

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
	<modelVersion>4.0.0</modelVersion>

	<groupId>com.someco</groupId>
	<artifactId>raml-tests</artifactId>
	<version>0.0.1-SNAPSHOT</version>
	<packaging>jar</packaging>

	<name>raml-tests</name>
	<url>http://maven.apache.org</url>

	<properties>
		<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
	</properties>

	<dependencies>
		<dependency>
			<groupId>junit</groupId>
			<artifactId>junit</artifactId>
			<version>3.8.1</version>
			<scope>test</scope>
		</dependency>
		<dependency>
			<groupId>com.fasterxml.jackson.core</groupId>
			<artifactId>jackson-core</artifactId>
			<version>2.8.8</version>
		</dependency>
		<dependency>
			<groupId>com.fasterxml.jackson.core</groupId>
			<artifactId>jackson-databind</artifactId>
			<version>2.8.8</version>
		</dependency>
		<dependency>
			<groupId>com.fasterxml.jackson.core</groupId>
			<artifactId>jackson-annotations</artifactId>
			<version>2.8.8</version>
		</dependency>
		<dependency>
			<groupId>com.fasterxml.jackson.dataformat</groupId>
			<artifactId>jackson-dataformat-yaml</artifactId>
			<version>2.8.8</version>
		</dependency>

		<!-- RAML -->
		<dependency>
			<groupId>org.raml</groupId>
			<artifactId>raml-generator-api</artifactId>
			<version>2.0.1-SNAPSHOT</version>
		</dependency>
		<dependency>
			<groupId>org.raml</groupId>
			<artifactId>raml-emitter</artifactId>
			<version>2.0.1-SNAPSHOT</version>
		</dependency>

	</dependencies>
</project>

GetResource.java:

package com.someco.ramltests;

import javax.ws.rs.GET;
import javax.ws.rs.Path;
import javax.ws.rs.Produces;

@Path("/contracts/{contractId}")
public class GetResource {
	@Produces("application/json")
	@GET
	public ResourceImpl test() {
		return null;
	}

}

ResourceImpl.java:

package com.someco.ramltests;

import java.util.Date;

import org.raml.emitter.plugins.DefaultTypeHandler;
import org.raml.jaxrs.common.RamlGenerator;
import org.raml.jaxrs.handlers.SimpleJacksonTypes;

import com.fasterxml.jackson.annotation.JsonProperty;

@RamlGenerator(SimpleJacksonTypes.class)
public class ResourceImpl {
	@JsonProperty
	Date d;
}

I execute the command:

java -jar jaxrs-to-raml-cli-2.0.1-SNAPSHOT-jar-with-dependencies.jar -a target/classes/ -o test.raml

On the standard out:

09:30:48.169 [main] INFO  o.r.jaxrs.parser.JerseyJaxRsParser - parsing JaxRs resource: target/classes
09:30:48.224 [main] DEBUG o.r.jaxrs.parser.JerseyJaxRsParser - found JaxRs related classes: 
[
  class com.someco.ramltests.GetResource
]
09:30:48.226 [main] DEBUG o.r.j.p.analyzers.JerseyAnalyzer - analyzing...
09:30:48.405 [main] DEBUG o.r.j.p.analyzers.JerseyAnalyzer - found jersey resources: 
[
  Resource{"/contracts/{contractId}", 0 child resources, 1 resource methods, 0 sub-resource locator, 1 method handler classes, 0 method handler instances}
]
09:30:48.407 [main] DEBUG o.r.j.p.analyzers.JerseyAnalyzer - found runtime resources: 
[
  org.glassfish.jersey.server.model.RuntimeResource@60704c
]
09:30:48.408 [main] DEBUG o.r.j.converter.JaxRsToRamlConverter - converting application: 
JaxRsApplication {
  Resource {
    path: /contracts/{contractId}
  }
}

and test.raml is:

#%RAML 1.0
title: Raml API generated from classes
version: 1.0
baseUri: http://www.baseuri.com
mediaType: "*/*"
/contracts/{contractId}:
    get:
        responses:
            200:
                body:
                    application/json:
                        type: ResourceImpl
types:
    ResourceImpl:
        properties:
            d: 
                type: Date
    void:
        properties:
    BaseCalendar:
        properties:
    int[]:
        properties:
    String[]:
        properties:
    Date:
        properties:

#2

any chance you could provide a snippet of code used to generate that RAML with empty definitions?


#3

I added more info in my post.

Thank you.


#4

Another thing that I noticed is that if a property is defined as an interface, for example:

Resource r;

Where Resource is an interface that extends another interface:

public interface Resource extends BaseResource {
    public int getX();
}

public interface BaseResource  {
    public int getY();
}

The type in the .raml file for Resource will contain only the property x and not y. This does not seem correct to me.


#5

I realized I never got around to reply. Sorry about that.

Would you mind trying to reproduce both issues with the latest 2.1.0 version of raml-for-jaxrs? Note that the groupId has changed from org.raml to org.raml.jaxrs. If you can still reproduce with that version, feel free to submit your issues on https://github.com/mulesoft-labs/raml-for-jax-rs.