Page Comparison

https://issues.folio.org/browse/MODUSERS-140

Description:

{quote}

There is a need to use external JSON schema(s) to describe data in RAML API interfaces.
The schema is expected to reside inside a jar file which attached to a module as a regular dependency.
If the above is not achievable – propose any options of how external schemas can be used in a module with minimal effort

{quote}

Input values:

assume existing RAML directory structure:

Code Block
\ramls -\examples -\raml-util -library.raml -nataliabook.json -bookCollection.json

where bookCollection.json file contains a reference to the single item

as following:

Code Block
"$ref": "nataliaBook.json"

Results:

1. Include JSON schemas as a dependency to the module using maven plugins

Approach:

add a dependency to the target module

include following plugins to the .pom file

Expand

title	Add a plugin to unpack RAML and JSON files

This plugin unpack the files of particular dependency

Code Block

<plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-dependency-plugin</artifactId>
        <version>3.1.0</version>
        <executions>
          <execution>
            <id>unpack</id>
            <phase>prepare-package</phase>
            <goals>
              <goal>unpack</goal>
            </goals>
            <configuration>
              <artifactItems>
                <artifactItem>
                  <groupId>org.folio</groupId>
                  <artifactId>mod-data-upload</artifactId>
                  <outputDirectory>${ramlfiles_path}</outputDirectory>
                  <overWrite>true</overWrite>
                  <includes>ramls/</includes>
                  <excludes>ramls/raml-util/, ramls/*.list</excludes>
                </artifactItem>
              </artifactItems>
              <overWriteReleases>false</overWriteReleases>
              <overWriteSnapshots>true</overWriteSnapshots>
            </configuration>
          </execution>
        </executions>
      </plugin>

Expand

title	Сlean up the folder

Info

the following property seems not working for the maven-dependency-plugin

this means that every time you need to build the project you have to remove the folder manually.

To simply this process add the maven-clean-plugin to do it automatically by specifying the folder

Code Block

<plugin>
        <artifactId>maven-clean-plugin</artifactId>
        <version>3.1.0</version>
        <configuration>
          <filesets>
            <fileset>
              <directory>ramls/ramls</directory>
              <followSymlinks>false</followSymlinks>
            </fileset>
          </filesets>
        </configuration>
      </plugin>

Expand

title	Add the ant-run plugin

After the module builds, all references to files will point to exact files in the current system:

which is not convenient to use in case of the different build environments.

The following plugin task will replace found lines, specifying the path to file and cut it to leave only the file name.

Code Block

<plugin>
        <artifactId>maven-antrun-plugin</artifactId>
        <version>1.8</version>
        <executions>
          <execution>
            <phase>prepare-package</phase>
            <goals>
              <goal>run</goal>
            </goals>
            <configuration>
              <tasks>
                <replaceregexp match="(file:.*[/])" replace="" byline="true">
                  <fileset dir="${ramlfiles_path}/ramls" includes="**/*.json" />
                </replaceregexp>
              </tasks>
            </configuration>
          </execution>
        </executions>
      </plugin>

Advantages:

No need to modify RMB module

Disadvantages:

Insert a bunch of plugins to every module needed
maintain regex in case of change

2. Add plugin to RMB to manage references

Approach:

From the jsonschema2pojo Wiki documentation and code example there is possible to specify the path to the referenced object by classpath:, resource:

Advantages:

Changes done in RMB will apply to all modules, which are used it

Disadvantages:

Need to modify RMB module
Need to investigate the amount of changes to RMB

3. Add schemas to RAML module

Approach:

Store RAML, JSON files in the FOLIO Raml module

Advantages:

All needed files stored in one place and modules can access it as other schemas already stored in RAML module

Disadvantages:

Raml module will store additional files, which probably not all of the modules are interested in.

Useful links:

Maven-Antrun-Plugin
Maven-Dependency-Plugin: Unpack

Maven jsonschema2pojo plugin and

Expand

title	Sample example of plugin

Code Block

<plugin>
    <groupId>org.jsonschema2pojo</groupId>
    <artifactId>jsonschema2pojo-maven-plugin</artifactId>
    <version>0.5.1</version>
    <configuration>
        <skip>false</skip>
        <sourceDirectory>${basedir}/src/main/resources/schema/json/modules/</sourceDirectory>
        <outputDirectory>${basedir}/src/gen/java/json</outputDirectory>
        <removeOldOutput>true</removeOldOutput>
        <annotationStyle>none</annotationStyle>
        <includeGetters>true</includeGetters>
        <includeSetters>true</includeSetters>
        <useCommonsLang3>true</useCommonsLang3>
        <useLongIntegers>true</useLongIntegers>
        <includeJsr303Annotations>true</includeJsr303Annotations>
        <includeAdditionalProperties>false</includeAdditionalProperties>
        <includeHashcodeAndEquals>false</includeHashcodeAndEquals>
        <dateTimeType>java.time.LocalDateTime</dateTimeType>
        <targetPackage>com.all.my.modules</targetPackage>
    </configuration>
    <executions>
       <execution>
            <phase>process-resources</phase>
            <goals>
               <goal>generate</goal>
            </goals>
       </execution>
    </executions>
</plugin>

Versions Compared

Old Version 9

New Version 10

Key

Results:

1. Include JSON schemas as a dependency to the module using maven plugins

2. Add plugin to RMB to manage references

3. Add schemas to RAML module