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.

Both OpenAPI 3.0 and Swagger 2.0 specs are supported and produce identical SDKs, including 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\Spec\OpenAPI3;
use Appwrite\SDK\SDK;
use Appwrite\SDK\Language\PHP;

// Read API specification file (OpenAPI 3) and create spec instance
$version = '1.9.x';
$platform = 'server';
$spec = new OpenAPI3(file_get_contents("https://raw.githubusercontent.com/appwrite/specs/main/specs/{$version}/open-api3-{$version}-{$platform}.json"));

// Swagger 2 specs are supported as well:
// use Appwrite\Spec\Swagger2;
// $spec = new Swagger2(file_get_contents("https://raw.githubusercontent.com/appwrite/specs/main/specs/{$version}/swagger2-{$version}-{$platform}.json"));

// 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
    ->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 an API specification, use StaticSpec:

<?php

require_once 'vendor/autoload.php';

use Appwrite\Spec\StaticSpec;
use Appwrite\SDK\SDK;
use Appwrite\SDK\Language\Skills;

$spec = new StaticSpec(
    title: 'Appwrite',
    description: 'Appwrite backend as a service',
    version: '1.9.x',
    licenseName: 'BSD-3-Clause',
    licenseURL: 'https://raw.githubusercontent.com/appwrite/appwrite/master/LICENSE',
);

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

$sdk
    ->setName('Appwrite')
    ->setVersion('1.9.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
• 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)

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. Both formats produce identical SDKs.

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