⚙️ 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.
$version = '1.9.x';
$platform = 'server';
$content = file_get_contents("https://raw.githubusercontent.com/appwrite/specs/main/specs/{$version}/open-api3-{$version}-{$platform}.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
    ->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' => '1.9.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('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.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. 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

Target	Argument	Supported Versions	Coding Standards	Package Manager	Output
Web	web	ES5+; Node.js >=18 for builds	NPM Coding Style	NPM	examples/web/
Flutter	flutter	Dart >=3.7 <4; Flutter >=3.29	Effective Dart	pub	examples/flutter/
Apple	apple	iOS 15+, macOS 11+, watchOS 7+, tvOS 13+	Swift Style Guide	Swift Package Manager	examples/apple/
Android	android	Android 6.0+; Java 17 in CI	Android style guide	Gradle, Maven	examples/android/
React Native	react-native	React Native >=0.76.7 <1.0.0; Node.js >=18	NPM Coding Style	NPM	examples/react-native/

Server SDKs

Target	Argument	Supported Versions	Coding Standards	Package Manager	Output
Node.js	node	Node.js 20 in CI	NPM Coding Style	NPM	examples/node/
PHP	php	PHP >=8.2	PHP FIG	Composer	examples/php/
Python	python	Python >=3.9	PEP8	pip	examples/python/
Ruby	ruby	Ruby 3.1 in CI	Ruby Style Guide	RubyGems, Bundler	examples/ruby/
Dart	dart	Dart >=2.17 <4	Effective Dart	pub	examples/dart/
Go	go	Go 1.26.5	Effective Go	Go modules	examples/go/
Swift	swift	Swift 5.1+; Swift 5.9.2 in CI	Swift Style Guide	Swift Package Manager	examples/swift/
.NET	dotnet	.NET Standard 2.0; .NET Framework 4.6.2	C# Coding Conventions	NuGet	examples/dotnet/
Kotlin	kotlin	JVM 1.8 target; Java 17 in CI	Kotlin style guide	Gradle, Maven	examples/kotlin/
Rust	rust	Rust >=1.83	Rust API Guidelines	Cargo	examples/rust/

Tooling and Documentation

Target	Argument	Supported Versions	Coding Standards	Package Manager	Output
CLI	cli	Go 1.26.5	Effective Go	Go modules, native binaries, NPM	examples/cli/
REST examples	rest	N/A	Markdown	N/A	examples/REST/
GraphQL	graphql	N/A	GraphQL	N/A	examples/graphql/
Skills	skills	N/A	Markdown	N/A	examples/skills/
Cursor Plugin	cursor-plugin	N/A	Markdown	N/A	examples/cursor-plugin/
Claude Plugin	claude-plugin	N/A	Markdown	N/A	examples/claude-plugin/
Codex Plugin	codex-plugin	N/A	Markdown	N/A	examples/codex-plugin/
Zed Extension	zed-extension	Zed extension API 0.7.0	Rust	Cargo	examples/zed-extension/

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