raml-for-jax-rs插件

簡介

raml-for-jax-rs插件是mulesoft開發的，是實作被JAX-RS注解的java代碼與Raml Api描述之間互相轉換的工具。

其中包含jaxrs-to-raml和raml-to-jaxrs兩個主要工程，分别實作一種轉換過程。

設計原則

RAML生成JAX-RS

所有發行版本（Eclipse Plugin，Maven Plugin和Jar）的工作方式如下：

• 生成接口，并在RAML定義改變的情況下重新生成接口
• 一個接口被生成一個頂級resource，該接口下面的子接口稱為sub-resouce被作為不同的方法定義在同一個接口下
• 為每個資源操作建立響應對象包裝器，以便指導實作者僅生成與RAML定義相容的結果
• 為不屬于JAX-RS核心規範的http方法生成自定義注解（PATCH）
• 對象基于代表 請求/響應 實體的json schemas來生成
• 英語是接口和方法中常用的語言

目前支援

• JAX-RS 1.1 和 2.0
• 除

  @Pattern

  外，JSR-303注解都支援，因為Raml用的是ECMA 262/Perl 5模式，而javax.validation用的是Java模式，

  @Min/@Max

  支援對raml中定義的非小數最大最小值的限制
• 模型對象基于JSON schemas生成，帶有Jackson1,2或者Gson注解
• 基于XML Schemas生成帶有JAXB注解的結果

JAX-RS注解

• Path
• Consumes, Produces.
• QueryParam, FormParam, PathParam, HeaderParam.
• DELETE, GET, HEAD, OPTIONS, POST, PUT.
• DefaultValue.

擴充注解

驗證注解：

• NotNull
• Min
• DecimalMin
• Max
• DecimalMax

支援方式

該插件支援以下幾種使用方式

• Maven 插件
• eclipse插件
• 指令行

Maven插件

這裡我們着重對Raml to JAX-RS方式中Maven插件的使用進行介紹

RAML to JAX-RS

這個Maven插件用來基于raml Api生成JAX-RS注釋的java接口，支援基于單一或多個RAML檔案

Maven 元件

Maven 元件倉庫位址

- https://repository-master.mulesoft.org/releases/ - release repository

- https://repository-master.mulesoft.org/snapshots/ - snaphots repository

使用方式

需要在Project中的Pom檔案中增加以下plug-in内容， 例如：

<plugin>
<groupId>org.raml.plugins</groupId>
<artifactId>raml-jaxrs-maven-plugin</artifactId>
<version>1.3.4</version>
<configuration>
    <!-- Use sourcePaths if you want to provide a single RAML file or a list of RAML files -->
    <sourceDirectory>${basedir}/raml</sourceDirectory>
    <!-- Optionally configure outputDirectory if you don't like the default value: ${project.build.directory}/generated-sources/raml-JAX-RS -->
    <!-- Replace with your package name -->
    <basePackageName>com.acme.api</basePackageName>
    <!-- Valid values: 1.1 2.0 -->
    <jaxrsVersion>2.0</jaxrsVersion>
    <useJsr303Annotations>false</useJsr303Annotations>
    <!-- Valid values: jackson1 jackson2 gson none -->
    <jsonMapper>jackson2</jsonMapper>
    <removeOldOutput>true</removeOldOutput>
    <!-- Optionally set extensions to a list of fully qualified names of classes
    that implement org.raml.jaxrs.codegen.core.ext.GeneratorExtension -->
    <!-- for example:
    <extensions>
        <param>com.abc.AuthorizationAnnotationExtension</param>
        <param>com.abc.ParameterFilterExtension</param>
    </extensions>
    Custom annotator for json schema to pojo convertor
    <customAnnotator>com.abc.MyCustomAnnotator</customAnnotator>
    -->
</configuration>
<executions>
    <execution>
        <goals>
            <goal>generate</goal>
        </goals>
        <phase>generate-sources</phase>
    </execution>
</executions>
</plugin>
           

配置說明

Schema	Mean	Optional
sourceDirectory	raml檔案目錄	custom
sourcePaths	raml檔案路徑集合	custom
outputDirectory	輸出目錄	custom
basePackageName	生成的基礎包路徑	custom
removeOldOutput	是否删除上一次的輸出	boolean
jaxrsVersion	JAX-RS規範版本	1.1 or 2.0
useJsr303Annotations	是否使用JSR303規範	boolean
jsonMapper	json與java映射規範	jackson1 jackson2 gson none
extensions	擴充對Resource的生成控制	custom
customAnnotator	json schema到pojo的定制化注解器	custom
jsonMapperConfiguration	對于json映射的配置	“generateBuilders”,”includeHashcodeAndEquals”,”includeToString”,”useLongIntegers”
skip	跳過插件的執行	boolean
modelPackageName	設定model對象所在的目錄名稱(basepackage+modelpackage,如果schema中已經指定了javapackage，則此配置不生效)	custom
generateClientProxy	是否生成用戶端代理(隻生成proxy，覆寫model和resource)	boolean
mapToVoid	true:如果resource定義的方法的response沒有body，生成的java method傳回值将會是void，不是wrapper response	boolean
useTitlePropertyForSchemaNames	将title屬性作為schema的名稱(沒試出來)	boolean
asyncResourceTrait	【待定】
ignoredParameters	定義忽略參數清單，忽略指定的resource query參數	custom

運作

mvn raml:generate

時，RAML定義的内容就會被處理生成相應的Java代碼，同樣在運作

mvn compile

或者

mvn package

指令時這個插件也會執行。