How TeaDSL Simplifies Multi‑Language SDK Generation for OpenAPI

Background

Alibaba Cloud engineer Pu Ling, after six years at Alibaba, noticed that while Alibaba Cloud offers first‑class cloud services, the developer experience for OpenAPI SDKs was lacking. He joined the Alibaba Cloud Open Platform SDK team and helped design the patented TeaDSL to solve multi‑language SDK challenges.

Pain Points of Using OpenAPI

Traditionally, OpenAPI interfaces are documented with minimal parameter descriptions and handed to customers, leaving developers to deal with unclear parameters, signature algorithms, language‑specific wrappers, network errors, and frequent API changes. Maintaining an OpenAPI also requires providing detailed documentation, SDKs, code samples, CLI tools, and test cases for each language, which becomes a massive manual effort as the number of gateways (M) and supported languages (N) grows.

Provide comprehensive API documentation.

Offer SDKs that encapsulate details and provide IDE hints.

Supply code samples to illustrate usage.

Include CLI tools for scripting.

Maintain test cases for continuous integration.

These requirements multiplied by multiple languages and gateway styles turn a simple task into a labor‑intensive process.

TeaDSL Solution

TeaDSL is a domain‑specific language designed to address the following problems:

Provide a unified intermediate language that can describe any gateway style.

Translate the intermediate representation into SDKs for multiple programming languages.

Generate code samples for OpenAPI interfaces uniformly across languages.

The core capability of TeaDSL is to describe OpenAPI, SDK, and code sample scenarios using a common syntax, enabling automatic generation of multi‑language artifacts.

Supporting Arbitrary Gateway Styles

Different API gateways have varied metadata formats. By focusing on the underlying HTTP protocol as the core model and separating data structures from serialization (e.g., toJSON, toXML), TeaDSL abstracts away gateway differences. A simplified model looks like:

{
  protocol: string, // http or https
  port: number,
  host: string,
  request: {
    method: string,
    pathname: string,
    query: map[string]string,
    headers: map[string]string,
    body: readable
  },
  response: {
    statusCode: number,
    statusMessage: string,
    headers: map[string]string,
    body: readable
  }
}

Developers define models (e.g., model User { username: string, age: number }) and use conversion functions ( toJSON, toXML) to handle serialization. An example API method in TeaDSL:

api getUser(username: string): User {
  __request.method = 'GET';
  __request.pathname = `/users/${username}`;
  __request.headers = { host = 'hostname' };
} returns {
  var body = readAsJSON(__response.body);
  return body;
}

This approach reduces the workload from M × N (gateways × languages) to M + N by introducing a middle layer.

Supporting Multiple Programming Languages

Instead of brittle template generation, TeaDSL provides its own lexical, syntactic, and semantic rules, allowing validation before code generation. This DSL‑based approach avoids naming conflicts and syntax errors common in template systems.

The generation pipeline transforms the intermediate representation into SDKs, code samples, and test cases for various languages, ensuring consistency and reducing manual effort.

Conclusion

TeaDSL enables consistent OpenAPI documentation, SDKs, CLI tools, and test cases across diverse gateway styles and programming languages, improving developer experience and significantly lowering the maintenance cost for OpenAPI providers. It is already used in several Alibaba Cloud SDKs and aims to become a more adaptable ecosystem than Swagger.