How Darabonba Transforms OpenAPI into Multi‑Language SDKs and Code Samples

Why a new DSL for OpenAPI?

Because each gateway has different backend characteristics, a single set of metadata cannot serve all OpenAPI definitions. Alibaba Cloud therefore created a new DSL called Darabonba to describe diverse OpenAPI styles and to support multi‑language SDK and Code Sample generation.

Multi‑language SDK generation

Traditional solutions such as Swagger rely on templates and JSON/YAML metadata, which are inflexible for non‑RESTful APIs. Darabonba describes OpenAPI with DSL code, which the Darabonba compiler turns into an AST. From this AST the SDK for any target language can be generated, eliminating the need for a universal JSON/YAML schema.

Modular design

Generating SDKs solely from data models leads to ever‑growing core libraries that become hard to maintain. Darabonba adopts a modular approach: functionality is split into separate modules (e.g., utilities, file upload, XML handling). This reduces coupling, eases testing, and prevents the “one‑big‑core‑library” problem.

Interface modules

Darabonba can declare interface modules that only specify method signatures. Implementations are provided in each target language. Example of a Console interface module:

/**
 * Console val with log level into stdout
 * @param val the printing string
 * @return void
 * @example [LOG] tea console example
 */
static function log(val: string): void;

Using the CLI, developers publish these modules to the Darabonba module repository: dara publish After publishing, a language‑specific SDK can import the module, e.g.:

import Console;

static async function main(args: [string]) throws : void {
  Console.log("hello world!");
}

OpenAPI modules

Each Darabonba project that describes an OpenAPI is itself an OpenAPI module. Publishing the module makes its methods and language‑specific installation instructions visible to SDK users.

Automatic Code Sample generation

Many customers struggle because SDKs lack runnable Code Samples. Darabonba can generate Code Samples for all supported languages directly from the OpenAPI description, ensuring they stay in sync with API changes. Example for the Voice Service SDK:

import Dyvmsapi;
import RPC;
import Console;

/**
 * Initialize client with AK&SK
 */
static function createClient(accessKeyId: string, accessKeySecret: string) throws : Dyvmsapi {
  var config = new RPC.Config{};
  config.accessKeyId = accessKeyId;
  config.accessKeySecret = accessKeySecret;
  return new Dyvmsapi(config);
}

static async function main(args: [string]) throws : void {
  var client = createClient("accessKeyId", "accessKeySecret");
  var request = new Dyvmsapi.QueryCallDetailByCallIdRequest{
    callId = "100625930001^10019107xx",
    prodId = 11000000300004L,
    queryDate = 1577255564
  };
  var response = client.queryCallDetailByCallId(request);
  Console.log(response.code);
}

Automatic Test Case generation

To ensure continuous availability of OpenAPI services, Darabonba can generate language‑agnostic test cases that are compiled into each SDK. Example test case:

import Assert;
import Dyvmsapi;
import RPC;

static function createClient(accessKeyId: string, accessKeySecret: string) throws : Dyvmsapi {
  var config = new RPC.Config{};
  config.accessKeyId = accessKeyId;
  config.accessKeySecret = accessKeySecret;
  return new Dyvmsapi(config);
}

static async function TestNumberEqual() throws : void {
  var client = createClient("accessKeyId", "accessKeySecret");
  var request = new Dyvmsapi.QueryCallDetailByCallIdRequest{
    callId = "100625930001^10019107xx",
    prodId = 11000000300004L,
    queryDate = 1577255564
  };
  var response = client.queryCallDetailByCallId(request);
  Assert.equal(response.code, 'OK', 'queryCallDetailByCallId is failed!');
}

Contribution

Darabonba invites developers to contribute by adding support for more languages, writing utility modules, improving the compiler and CLI, and creating tools to convert existing OpenAPI metadata into Darabonba.