A mainstay of service-oriented integration is contract first design to accelerate development and facilitate a test driven development approach. When it comes to APIs the most widely accepted ‘contract’ definition standard is the OpenAPI specification, previously known as the Swagger Specification. In contrast the MuleSoft technology stack relies on the RAML specification, which is natively supported across its API Gateway and ESB products.
Due to the large base of tooling and community support that OpenAPI offers, you may prefer to make use of the OpenAPI standard to define your contracts instead of RAML. In this blog we will show you how to import the types defined in an OpenAPI definition into Anypoint Studio for development use in MuleESB.
Step 1
Once your OpenAPI contract has been defined, the first step is to generate a Java client library version of the contract (json) objects. This is easily achieved in the OpenAPI (Swagger) editor by expanding the ‘Generate Client’ dropdown and choosing ‘Java’.
This will result in a zip file containing Java source code of the OpenAPI specification. Save this file and unzip it.
Step 2
The OpenAPI generated source utilises com.fasterxml.jackson.annotation.JsonProperty whereas Mule currently only supports the older org.codehaus.jackson.annotate.JsonProperty to map to a JSON field or object name via the ‘JsonProperty’ annotation, so run a ‘find and replace’ for this on the extracted source.
In a Linux based command terminal this can be performed as follows:
- find . -type f -name “*.java” -exec sed -i ‘s/com.fasterxml.jackson.annotation/org.codehaus.jackson.annotate/g’ {} +
Since we are only interested in the types which have been generated, we will remove a few references which are not required as follows:
- find . -type f -name “*.java” -exec sed -i ‘/ApiModel/d’ {} +
- find . -type f -name “*.java” -exec sed -i ‘/ApiModelProperty/d’ {} +
Step 3
Create the io/swagger/client/model directory hierarchy within the Mule project’s src/main/java directory and copy the modified files in the io/swagger/client/model folder to the Mule project’s src/main/java/io/swagger/client/model directory.
Step 4
In Mule Anypoint Studio, refresh the src/main/java folder. To utilise these object types in a flow transformer select the transformer within the flow and in the input or output mapping area, either click ‘Define metadata’ (if no existing metadata has been provided), or right click and select ‘Set Metadata’ (if metadata already exists) for a specific payload or variable object. In the concurrent ‘Define Type’ window:
- Select ‘Create new type’
- Select ‘JAVA’ as the type
- Provide a type id (arbitrary)
- In the ‘Data structure’ area, select the desired java type (type the object name in the search text box and choose the object from the local workspace io.swagger.client.model)
- Click ‘Finish’
The output of a mapping using this metadata definition will be a Java object in the Mule flow, but is easily transformed into a JSON object via the ‘Object to JSON’ transformer in a Mule flow (where required).
This will allow a developer to import an OpenAPI definition in order to accurately and efficiently map from/to the correct structure of a JSON object as well as in other Mule ESB flow development artefacts like a Mule Expression Language dropdown choice.
