appwrite/sdk-generator

⚙️ Appwrite SDK Generator

Appwrite SDK generator is a PHP library for auto-generating SDK libraries for multiple languages and platforms.

The SDK Generator uses predefined language settings as Twig templates to generate codebases based on different API specs.

Utopia OpenAPI parses OpenAPI 2.0, 3.0, and 3.1 documents into one canonical model. The generator consumes that model to render services, methods, models, enums, and union types.

Getting Started

Install using composer:

CLI

composer update --ignore-platform-reqs --optimize-autoloader

Docker (UNIX)

docker run --rm --interactive --tty --volume "$(pwd)":/app composer install --ignore-platform-reqs

Docker (Windows)

docker run --rm --interactive --tty --volume "%cd%":/app composer install --ignore-platform-reqs

Create language and SDK instances and generate code to target directory.

<?php

require_once 'vendor/autoload.php';

use Appwrite\SDK\SDK;
use Appwrite\SDK\Language\PHP;
use Utopia\OpenAPI\Parser;

// Parse an OpenAPI 2, 3.0, or 3.1 document into the canonical specification model.
// One document covers every SDK platform; the SDK selects its own below.
$version = '2.4.x';
$platform = 'server';
$content = file_get_contents("https://raw.githubusercontent.com/appwrite/specs/main/specs/{$version}/open-api3-{$version}.json");
$spec = Parser::parse($content);

// Create language instance
$lang = new PHP();

$lang // Set language or platform specific options
    ->setComposerPackage('my-api')
    ->setComposerVendor('my-company')
;

// Create the SDK object with the language and spec instances
$sdk  = new SDK($lang, $spec);

$sdk
    ->setPlatform($platform) // Keep the operations, aliases and security schemes available to this platform
    ->setCoverImage('https://github.com/appwrite/appwrite/raw/main/public/images/github.png')
    ->setLicenseContent('License content here.')
    ->setVersion('v1.1.0')
;

$sdk->generate(__DIR__ . '/examples/php'); // Generate source code

For generated artifacts that do not need API operations, create a minimal canonical specification:

<?php

require_once 'vendor/autoload.php';

use Appwrite\SDK\SDK;
use Appwrite\SDK\Language\Skills;
use Utopia\OpenAPI\Parser;

$spec = Parser::parse([
    'openapi' => '3.0.0',
    'info' => [
        'title' => 'Appwrite',
        'description' => 'Appwrite backend as a service',
        'version' => '2.4.x',
        'license' => [
            'name' => 'BSD-3-Clause',
            'url' => 'https://raw.githubusercontent.com/appwrite/appwrite/master/LICENSE',
        ],
    ],
    'paths' => [],
]);

$sdk = new SDK(new Skills(), $spec);

$sdk
    ->setName('Appwrite')
    ->setVersion('2.4.x')
;

$sdk->generate(__DIR__ . '/examples/skills');

Linting Twig Templates

This project uses djLint to lint Twig template files for syntax and common issues.

Note: Formatting is disabled as it breaks code generation syntax. Only linting is used.

Available command:

composer lint-twig  # Check for linting errors

Requires uv to be installed. Configuration is in pyproject.toml. The linter runs automatically on pull requests via GitHub Actions.

Supported Specs

• OpenAPI 3.1
• OpenAPI 3.0
• OpenAPI (Swagger) 2
• RAML 1.0 (Not Ready)
• RAML 0.8 (Not Ready)
• Postman 2.0 (Not Ready)
• Postman 1.0 (Not Ready)
• API Blueprint 1A (Not Ready)

Naming enum values

Enum wire values are converted into identifiers for each generated language. To give values explicit semantic names, describe the enum as titled oneOf branches. This is especially useful when values contain non-Latin text:

title: ProvinceType
type: string
oneOf:
  - title: Capital
    enum: [រាជធានី]
  - title: Province
    enum: [ខេត្ត]

OpenAPI 3.1 specifications can use const instead of a single-value enum. When a value has no explicit title and cannot form a valid identifier, the generator uses a deterministic positional name such as Value1.

Generated SDKs and Artifacts

The primary generation targets are defined in example.php. Run it without arguments to generate every target with the default console platform spec, or pass a target and optional platform to generate one SDK:

php example.php
php example.php <target>
php example.php <target> <platform>
php example.php <target> <platform> <format>

<platform> can be console, client, or server. If omitted, it defaults to console.

<format> can be openapi3 or swagger2. If omitted, it defaults to openapi3. Remote OpenAPI 3 generation uses the current 2.4.x specs; because Swagger 2 documents are not published for 2.4.x, remote Swagger 2 generation uses the latest available 1.8.x specs.

Examples:

php example.php web client
php example.php node server
php example.php cli console
php example.php skills
php example.php zed-extension

Client SDKs

Server SDKs

Tooling and Documentation

Contributing

All code contributions, including those by people with commit access, must go through a pull request and be approved by a core developer before being merged. This is to ensure proper review of all the code.

We truly ❤️ pull requests! If you wish to help, you can learn more about how you can contribute to this project in the contribution guide.

Copyright and license

The MIT License (MIT) http://www.opensource.org/licenses/mit-license.php