Generate PlantUML from RAML API

Introduction

In this story we will continue our last series (see https://medium.com/another-integration-blog/design-your-mulesoft-api-with-plantuml-ed892b33a620) about managing our API Design with Anypoint and PlantUML by generating and converting our RAML API to a PlantUML diagram.

Prerequisites

Install Graphviz

First we need to install Graphviz in our current installation (in my case macOS).

Graphviz is open source graph visualization software used to represent structural information as diagrams of abstract graphs and networks. It has important applications in networking, bioinformatics, software engineering, database and web design, machine learning, and many fields in visual interfaces and for other technical domains.

Launch the following command (using Hombrew in my case):

% brew install graphviz

Install oas-raml-converter

oas-raml-converter (https://www.npmjs.com/package/oas-raml-converter) is a useful Node.js tool that allows you to convert your RAML API to other formats (OAS 2.0, OAS 3.0…).

I will use it in my case to convert the Anypoint project that I created in Anypoint Code Builder, and then import it into my local environment as an OAS 2.0 project before generating the PlantUML diagram.

The installation is simple you only need to have a current installation of Node.js in your local development environment and follow the instructions described on the official website (we chose to use the command line option):

git clone https://github.com/mulesoft/oas-raml-converter.git
npm run build

After that your tool is available as a command line option :

% oasRamlConverter/oas-raml-converter/lib/bin/converter.js --from RAML --to OAS20 helloraml.raml > hello.yaml

helloraml.raml is the API RAML sample imported in my Anypoint Code Builder editor inside VS Code:

#%RAML 1.0
title: HelloRaml

/helloworld: # optional resource
  get: # HTTP method declaration
    responses: # declare a response
      200: # HTTP status code
        body: # declare content of response
          application/json: # media type
            type: | # structural definition of a response (schema or type)
              {
                "title": "Hello world Response",
                "type": "object",
                "properties": {
                  "message": {
                    "type": "string"
                  }
                }
              }
            example: | # example of how a response looks
              {
                "message": "Hello world"
              }

My Open API hello.yaml is now generated and I can use the Java library tool openapi-to-plantuml available at https://github.com/davidmoten/openapi-to-plantuml/ which allows me to generate a PlantUML Class Diagram from an OpenAPI 3.0 definition (YAML or JSON).

You can generate the last version using the following command line:

% mvn clean install

After that you can put the generated jar file in your classpath and launch it inside your Anypoint Code Builder project terminal inside VS Code:

% java -DPLANTUML_LIMIT_SIZE=8192 -jar openapi-to-plantuml-0.1.29-SNAPSHOT-jar-with-dependencies.jar single hello.yaml PUML hello.puml

The PlantUML file hello.puml code is generated as you can see:

@startuml
hide <<Path>> circle
hide <<Response>> circle
hide <<Parameter>> circle
hide empty methods
hide empty fields
skinparam class {
BackgroundColor<<Path>> Wheat
}
set namespaceSeparator none
class "GET_helloworld" <<Path>> <<GET /helloworld>> {
}
class "GET_helloworld 200" <<Response>> {
}
"GET_helloworld" ..> "1" "GET_helloworld 200" : "200"
@enduml

Click on Previsualize Diagram available by right clicking in the vscode editor like below to see the result of the display PlantUML diagram inside VS Code and Anypoint Code Builder:

As you can see, we have combined the best of two worlds - PlantUML for designing and documenting our API, and API Designer with Anypoint Code Builder to design our specification!

In our next series, we will continue our journey by integrating our Spring Boot Java code with some Anypoint assets like RAML using some cool plugins, so stay tuned !…