Problem Faced

Last week, I received a minor Change Requirement from the Client to add a field in the API Specs (RAML)

The requirement was critical, and so I quickly made the RAML change in code, pushed it to Github Repo, and got it merged to Dev. 

What I missed was: updating the same change in the corresponding API in exchange.

Though I pushed those changes to exchange the next day (I got another Change Request, and while publishing the RAML change to Exchange, I remembered what I missed. 

By the way, we do have a checklist to be followed for every new CR that is raised, but the change was so minor and critical, that I neglected the Checklist!

What is RAML Sync Verifier Plugin?

The custom plugin:

• Checks if the Raml in API implementation project is in Sync with the Raml in Exchange

• Gives you options to pass various configurations

• Fails the build if the RAMLs are not in sync with each other (This configuration can be turned off).

Why Is It Required

The RAML published to Exchange and the Raml in your API implementation should be in SYNC for a particular environment. 

There are plenty of good reasons for that: 

• Maintaining consistency of code

• Version control

• Reusing Fragments and canonicals 

Note: Adding the API ID (From API Manager) and Autodiscovery will not make the RAML in code in sync with exchange.  

I hate making the same mistake twice (At least when it comes to Tech Stuff!), so I created a very simple custom Maven plugin, which, during the build process, checks if the RAMLS are in sync.

Source Code Link

I will be describing briefly about the Plugin code, and the complete code with example mule app can be found at GitHub Repo

Pre-Requisites:

• Knowledge about developing Maven Custom Plugin

• Knowledge about Mule 4 apps and Anypoint Platform

• Anypoint Studio Installed 

• Maven installed 

• Eclipse installed

• Valid AnyPoint Credentials

• Have developed a simple Mule app with a basic API spec in design center using above credentials

About the Code

Project Structure

The Plugin has just one Mojo. A Java mojo consists simply of a single class representing one plugin's goal.

Exchange API Used 

• Access Management API: For obtaining Access Token

• Cloudhub Graph API: To Get the URL to download Raml (Zip) from Exchange

About The Mojo

• Goal Name: verify-raml

• Default Phase: TEST

• Parameters Matrix

Behind the Scene Logic

As mentioned in the Properties Matrix, you are required to pass the appropriate values of the parameters. The GitHub repo also has a sample mule app using the plugin, so you can see the usage of the plugin there as well.

Flow Diagram

The flow diagram can also be found at draw.io.

Steps

• Obtain Anypoint Platform Access token using https://anypoint.mulesoft.com/accounts/login

• Using Cloudhub GraphQL API, get the URL to download the RAML from Exchange

• Sample Response

• Download and unzip the zip file in a temp directory

• Compare the unzipped folder with the folder present in the project (default src/main/resources/api/)

• Using 

  Java

   

  
  

  
  

  
  

  
  

  x

  
  

  
  

   

  1

  Files.walkFileTree(one, new SimpleFileVisitor<Path>()

  
  

  
  

• Comparison is done byte by byte in size, but can be expanded as per your requirements

• If difference in size is detected, then detailed logs are displayed in the build console

Note:

You might face an issue on importing the GitHub code in Eclipse. Please mark the goal descriptor as ignored.

Testing the Plugin

Installing the Custom Maven Plugin in Your Local System

1.       Clone the custom plugin code from GitHub Repo.

2.       Open command prompt and browse to the cloned project Root Dir

3.       Run mvn clean install

Testing the Maven Plugin in A Sample Mule App

1.       Clone the sample Mule app from GitHub repo

2.       Open the command prompt and browse to the cloned project Root Dir

3.       Run mvn clean test.

 The plugin will be executed during the test phase based on the defaultPhase Configuration in the Mojo.

xxxxxxxxxx

@Mojo(name = "verify-raml", defaultPhase = LifecyclePhase.TEST)

Notes on The Sample Mule App

• You should include the plugin with its required configurations in order to use the plugin. 

• You can check out the usage in the pom.xml of the sample app

xxxxxxxxxx

<plugin>

    <groupId>com.apisero.plugin.maven</groupId>

    <artifactId>raml-sync-checker</artifactId>

    <version>0.0.1</version>

    <executions>

        <execution>

            <goals>

                <goal>verify-raml</goal>

            </goals>

        </execution>

    </executions>

    <configuration>

        <scope>test</scope>

        <anypoint.password>${anypoint.password}</anypoint.password>

        <anypoint.username>${anypoint.username}</anypoint.username>

        <download.directory>${download.directory}</download.directory>

        <raml.path>src/main/resources/api</raml.path>

        <exchange.version>latestVersionsOnly</exchange.version>

        <failOnError>true</failOnError>

   </configuration>

</plugin>

• I have excluded the credentials from my pom.xml, and I would recommend creating a simple API in the design center using your any point credentials and test out the plugin. 

Test Runs

First Run

Raml in exchange is in sync with the raml in sample-mule-app

The plugin will be executed during the test phase based on the defaultPhase Configuration in the Mojo.

@Mojo(name = "verify-raml", defaultPhase = LifecyclePhase.TEST)

Second Run

Raml in exchange is not sync with the raml in sample-mule-app. 

I manually added another endpoint in raml of sample-mule-app

The output on running mvn clean test: