The Spring MVC-RAML project aims to enforce contract-first approach for projects using Spring MVC framework. The idea is to manually maintain RAML file as a single source of truth and to use this plugin to generate web layer - Spring controllers and domain objects. If the plugin is used as part of a build, application's code will always be in line with RAML documentation.
The plugin is designed to be run on Java 8 code which has been compiled with argument name information.
A sample project that includes a SpringMVC Server implementation using the Decorator pattern as well as a RestTemplate based REST client is available here: SpringMVC RAML Contract First Sample. This sample is based on the contract first scenario whereby the RAML document is authored and used as the basis for implementation
Usage and documentation are available in the Javadoc and README.md (this file). Kindly contact the developers via email (available in the pom files) if required or open an Issue in our tracking system.
The SpringMVC-RAML plugin uses a Maven-based build system.
Git and JDK 8 update 20 or later
Be sure that your JAVA_HOME environment variable points to the jdk1.8.0 folder
extracted from the JDK download.
The SpringMVC-RAML plugin is released under version 2.0 of the Apache License.
Pull requests are welcome; Be a good citizen and create unit tests for any bugs squished or features added
The first step is to download and compile these projects using Maven. Simply run mvn clean install in the parent directory and artifact will be compiled. These can optionally be deployed to your Artifactory or similar repo.
Then simply include the following code in the POM of the project you wish to generate RAML for
<plugin>
<groupId>com.phoenixnap.oss</groupId>
<artifactId>springmvc-raml-plugin</artifactId>
<version>2.x.x</version>
<configuration>
<ramlPath>{path.to.raml.file}</ramlPath>
<schemaLocation>{path.to.schema.directory||schema.absolute.url}</schemaLocation>
<outputRelativePath>/src/generated</outputRelativePath>
<addTimestampFolder>false</addTimestampFolder>
<basePackage>com.gen.wow</basePackage>
<baseUri>/api</baseUri>
<generateUnreferencedObjects>true</generateUnreferencedObjects>
<generationConfig>
<includeAdditionalProperties>false</includeAdditionalProperties>
...
</generationConfig>
<seperateMethodsByContentType>false</seperateMethodsByContentType>
<rule>com.phoenixnap.oss.ramlplugin.raml2code.rules.Spring4ControllerStubRule</rule>
<ruleConfiguration>
</ruleConfiguration>
</configuration>
<executions>
<execution>
<id>generate-springmvc-endpoints</id>
<phase>compile</phase>
<goals>
<goal>generate-springmvc-endpoints</goal>
</goals>
</execution>
</executions>
</plugin>
(required) The path to the file, relative to the project base directory
(optional, default: "") Relative path where the generated Java classes will be saved to. Package structure folders will be created relative to this path.
(optional, default: false) Should an extra folder be generated using a timestamp to seperate generations
(required) Base package to be used for the java classes to be generated. Model objects will be added in the .model subpackage
(optional, default: "") The URI or relative path to the folder/network location containing JSON Schemas
(optional, default: "") Base URI for generated Spring controllers. This overrules the baseUri attribute from inside the .raml spec.
(optional, default: false) Determines whether POJOs for unreferenced schemas or data types included in the RAML file should be generated.
(optional) This object contains a map of configuration for the JsonSchema2Pojo generator. The full list of configurable attributes, their description and default values can be found here GenerationConfig
(optional, default: false) If set to true, we will generate a HttpHeaders parameter for each method to allow using request HTTP headers directly.
(optional, default: false) Should we generate separate API methods for endpoints which define multiple content types in their 200 response.
(optional, default: false) If set to true, we will generate Jackson 1 annotations inside the model objects.
(optional, default: 1) Levels of resource path that will be included in generated class names. If set to -1 entire uri will be included in class name.
(optional, default: 0) Top level of resource path that will be included in generated class names. If set to 0 entire URI will be included in class name.
(optional, default: false) Reverse order of resource path that will be included in generated class names. If set to false URI will be included in class name from left to right.
(optional, default: DEFAULT) Logic used for Java names of arguments and methods generation. Possible values: DEFAULT, DISPLAY_NAME (displayName attribute will be cleaned and used), ANNOTATION (value of javaName annotation will be used as is).
(optional) This is a key/value map for configuration of individual rules. Not all rules support configuration.
(optional, default: com.phoenixnap.oss.ramlplugin.raml2code.rules.Spring4ControllerStubRule) The rule class to be used for code generation.
- com.phoenixnap.oss.ramlapisync.generation.rule.Spring4ControllerStubRule: The standard rule. It creates simple controller stubs classes with Spring MVC annotations and empty method bodies (like in v.0.2.4). All you have to do is to implement the empty method body for each endpoint. This is simple and easy. The drawback: When you regenerate the controller stubs your code will be overriden.
Configuration:
callableResponse: [OPTIONAL] set to 'true' to support asynchronous callables. Default: 'false'
- com.phoenixnap.oss.ramlplugin.raml2code.rules.Spring4ControllerDecoratorRule: Creates a controller interface and a decorator with Spring MVC annotations for each top level endpoint. The decorator implements the controller interface and delegates all method calls to an @Autowired ControllerDelegate. So all you have to do is to provide an ControllerDelegate class which implements the controller interface.
Configuration:
callableResponse: [OPTIONAL] set to 'true' to support asynchronous callables. Default: 'false'
- com.phoenixnap.oss.ramlplugin.raml2code.rules.Spring4ControllerInterfaceRule: Creates an single interface with Spring MVC annotations for each top level endpoint. All you have to do is to provide an implementation for the controller interface
Configuration:
callableResponse: [OPTIONAL] set to 'true' to support asynchronous callables. Default: 'false'
simpleReturnTypes: [OPTIONAL] set to 'true' to generate controllers method's return types without ResponseEntity<> wrapper. Will also generate Object instead of ResponseEntity<?> return type for methods when return type is not specified for the endpoint. Default: 'false'
useShortcutMethodMappings: [OPTIONAL] set to 'true' to generate new shortcut method annotations(e.g. @PutMapping, @GetMapping) instead of old-style @RequestMapping. Default: 'false'
- com.phoenixnap.oss.ramlplugin.raml2code.rules.Spring4RestTemplateClientRule: Creates a single interface as well as a client implementation using the Spring RestTemplate. The client assumes that a RestTemplate is available to be autowired.
Configuration:
baseUrlConfigurationPath: The path that will be used to load the property for the server url. Default: ${client.url}
restTemplateFieldName: The name of the RestTemplate field
restTemplateQualifierBeanName: [OPTIONAL] The name of the bean for the rest template used in the generated client. Default: NONE
- com.phoenixnap.oss.ramlplugin.raml2code.rules.SpringFeignClientInterfaceRule:
Creates a standalone
org.springframework.cloud.netflix.feign.FeignClient(REST client) for each top level endpoint.