Design your MuleSoft API with PlantUML

By Karim DJAAFAR

Tech Lead Integration Architect from Jasmine Conseil

Introduction

In the world of information architecture, UML still has a strong foothold in the architecture of IT projects.

Therefore class diagrams are still desired, even when designing RESTful APIs.

In this post, I will describe how PlantUML an popular open-source tool and syntax for creating diagrams from plain-text definitions, combined with Anypoint Code Builder, the new IDE from MuleSoft/Salesforce can help you design and efficiently document your API project.

Prerequisite

First of all, you need to successfully install Anypoint Code Builder inside the Visual Studio Code IDE (VS Code) by going to the Visual Studio Marketplace to download the extension.

The official URL is Anypoint Extension Pack — Visual Studio Marketplace.

Click on the install option on the portal and this will redirect the request to your already open Visual Studio Code and allow you to install the extension.

Alternatively, you can also directly open Visual Studio Code, browse to the marketplace in the app and search for the Anypoint Extension Pack.

When you install the Anypoint Extension Pack, it also by default installs the various extension required by Anypoint Code Builder.

Once these extensions are installed you should be able to see the MuleSoft tab on the left panel as shown below.

Now it is time to install PlantUML.

Adding PlantUML extension to VS Code

The install is straightforward:

Go to VS Code -> Extensions and download the PlantUML plugin.

Don’t forget to install Graphviz, Graphviz is a graph visualisation software that is used by PlantUML to generate diagrams. PlantUML uses Graphviz to render various types of diagrams:

% brew install graphviz

Creating your first API specification with Anypoint Code Builder

Let’s start by going to the Design Center of Anypoint Code Builder.

The Code Builder Design Center is your cloud-based environment for building API specifications.

For this project, we will focus on API specifications.

Click on Design an API, you should enter your credentials:

After you’re logged in, scroll to Design Center and click Design an API

Enter BookStore in the Project name field and select OAS 3.0 (YAML) for the API specification language and leave the default selection as is:

Click on Create Project, the API specification window should appear with the bookstore.yaml file opened:

Delete the default text in the API Designer textbox so it’s empty.

Copy and paste the following RAML into the blank API Designer textbox.

openapi: 3.0.0
info:
  title: Book Management API
  description: An API to manage a collection of books
  version: 1.0.0

  servers:
    - url: http://localhost:8000
  paths:
    /books:
      get:
        summary: Get a list of books
        responses:
          '200':
            description: Successful response
      post:
        summary: Add a new book
        requestBody:
          content:
            application/json:
              schema:
                type: object
                properties:
                  title:
                    type: string
                  author:
                    type: string
                required:
                  - title
                  - author
        responses:
          '201':
            description: Book created successfully
          '400':
            description: Bad request
    /books/{id}:
      get:
        summary: Get a book by ID
        parameters:
          - in: path
            name: id
            schema:
              type: integer
              required: true
              description: Book ID
      responses:
        '200':
          description: Successful response
        '404':
          description: Book not found

In this example, we’ll create a simple API for managing a collection of books and we’ll use the YAML format to define the OpenAPI specification.

To demonstrate the API inside Anypoint Code Builder, let’s set up a basic server using Node.js and Express.js by creating a new file named server.js like bellow:

const express = require('express');
const app = express();
const port = 8000;

// Middleware to parse JSON request bodies
app.use(express.json());

// Endpoint to get a list of books
app.get('/books', (req, res) => {
  // Your implementation to fetch the list of books from a database or other data source
  const books = [
    { id: 1, title: 'Designing APIs with Swagger and OpenAPI', author: 'Joshua S. Ponelat' },
    { id: 2, title: 'Microservices APIs using Python,OpenAPI and more', author: 'Jose Haro Peralta' },
  ];

  res.json(books);
});

// Endpoint to add a new book
app.post('/books', (req, res) => {
  // Your implementation to add a new book to the database or other data source
  const { title, author } = req.body;
  const newBook = { id: 3, title, author };
  res.status(201).json(newBook);
});

// Endpoint to get a book by ID
app.get('/books/:id', (req, res) => {
  // Your implementation to fetch a book by ID from the database or other data source
  const bookId = parseInt(req.params.id);
  const book = { id: bookId, title: 'Eclipse et JBoss', author: 'K. DJAAFAR' };
  res.json(book);
});

app.listen(port, () => {
  console.log(`Server is running on http://localhost:${port}`);
});

NOTE

A version of Node.js must be installed on your local machine for this example.

Don’t forget also to install Express.js, using the command npm install express

Now open your terminal and navigate to the folder where the server.js and bookstore.yaml files are located.

Now, run the server using node server.js.

You should see a message confirming that the server is running on http://localhost:8000.

Now you can access the endpoints using Anypoint Code Builder like below (notice the http://localhost:8000 inside the OpenAPI specification):

Click on the GET operation:

Click on Try It and Send:

Return to the Back page and try GET /{Id}:

Click Try It again and select 3 as required field to get the Book by Id:

OK now that we have validated and tested our API specification, we can generate our diagram using PlantUML. We will use the Java library openapi-to-plantuml available at https://github.com/davidmoten/openapi-to-plantuml.

To generate the diagram, launch the following command:

% java -jar -CLASSPATH bookstore.yaml PNG bookstore.png

where,

· CLASSPATH is equal to the complete path to the directory that contains openapi-to-plantuml-0.1.23-SNAPSHOT-jar-with-dependencies.jar which is the jar generated with the maven command mvn clean install

· bookstore.yaml the OpenAPI specification of your local Anypoint project

· bookstore.png the resulted generated diagram

Here the generated class diagram inside Visual Studio Code:

Conclusion

Hope that this post was useful to enhance your design and document your API.

Next post we will see how PlantUML can generate your API inside Anypoint Code Builder IDE.