Generating a Mock Service for Ballerina

Ballerina is an upcoming programming language which is developed for cloud centric application development and to make life easier of cloud application developers. It has got tons of cool features under the hood and tools a developer could take advantage of.

With this article I’m going to explain the how to generate a mock service for a given OpenApi document using ballerina OpenApi Tool. I will be using the ballerina 1.0.1 distribution for this tutorial and if you have not yet downloaded the distribution get it from here.

This tutorial will be done in a MacOs Environment. The steps are mostly same for the rest of the platforms as well.

Step 1 : Ballerina Installation

Run the downloaded installer and complete the installation. The installer will install ballerina to a default location in your system. If needed you could give a custom location as per your convenience.

To validate the installation, use a console and run the following command.

ballerina -v

The response of the command will look as in the below image.

Note : if u need further guide on installation, please visit the Ballerina Getting started guide.

Step 2 : Generate a Ballerina Project

For the rest of the steps we would need to create a new ballerina project. To create a ballerina project run ballerina new <project-name> in the console. I’ll be using a project named openapi-gen-service for this.

ballerina new openapi-gen-service

The above command will generate a new folder with the name given in the command. For me it would be openapi-gen-service. For the next step we would need an OpenApi contract file so that we can generate the mock service. I’ll be using the sample provided in the OpenApi Specification git repo. You could download the same contract file here.

Save the downloaded file to a local location.

Step 3 : Generate Mock Service

This would be the final step in the tutorial which will be generating the mock service for the previously downloaded OpenApi contract. The command for this is ballerina openapi gen-service <module-name>:<service-name> <openapi-contract> .

ballerina openapi gen-service petstore:petstoreservice ../petstore.yaml

Output of the command.

The folder structure of the ballerina project will look as following.

The generation process will create a module with the name given in the gen-service command. The module will consist of a Module.md file which will be a descriptive MD file. A resources folder where the contract would be copied into for further use within the ballerina project. petstoreservice.bal which will have the generated service and schema.bal which will have the data types that are required for the service.

File contents : petstoreservice.bal

import ballerina / http;
import ballerina / openapi;
listener http: Listener ep0 = new(80, config = {
    host: "petstore.swagger.io"
});
@openapi: ServiceInfo {
    contract: "/Users/imeshchandrasiri/openapi-gen-service/src/petstore/resources/petstore.yaml"
}
@http: ServiceConfig {
    basePath: "/v1"
}
service petstoreservice on ep0 {
@http: ResourceConfig {
        methods: ["GET"],
        path: "/pets"
    }
    resource
function listPets(http: Caller caller, http: Request req) returns error ? {
}
@http : ResourceConfig {
        methods: ["POST"],
        path: "/pets"
    }
    resource
function createPets(http: Caller caller, http: Request req) returns error ? {
}
@http : ResourceConfig {
        methods: ["GET"],
        path: "/pets/{petId}"
    }
    resource
function showPetById(http: Caller caller, http: Request req, string petId) returns error ? {
}
}

File Contents : schema.bal

public type Pet record {
    int id;
    string name;
    string tag;
};
public type Pets record {
    Pet[] pet;
};
public type Error record {
    int code;
    string message;
};

You could further edit the petstoreservice.bal to implement the application logic of your choice. This is just a small tutorial of what you could achieve with the Ballerina Language. Please try our examples as well to see all the functionalities Ballerina has.