Download the PHP package crescat-io/saloon-sdk-generator without Composer

Saloon SDK Generator - Simplified SDK Scaffolding 🚀

Introducing the Saloon SDK Generator – your tool for quickly creating the basic structure of PHP SDKs using the powerful Saloon package.

Please note: This tool helps you set up the foundation for your SDK, but it might not create a complete, ready-to-use solution. 🛠️

Whether you're using Postman Collection JSON files (v2.1) or OpenAPI specifications, the Saloon SDK Generator simplifies the process of generating PHP SDKs. It provides you with a starting point to build the initial framework for your API interactions.

Keep in mind that the generated code might not be perfect for every situation. Think of it as a speedy way to scaffold your SDK structure. While you might need to customize it for specific cases, the Saloon SDK Generator saves you time by eliminating the need to create boilerplate code from scratch.

Your journey to crafting a tailored SDK starts here – with the Saloon SDK Generator. 🌟

Installation

You can install this package using Composer:

Usage

Generate SDK from OpenAPI or Postman Collection

To generate the PHP SDK from an API specification file, run the following command:

Replace the placeholders with the appropriate values:

• API_SPEC_FILE: Path to the API specification file (JSON or YAML format).
• --type: Specify the type of API specification (postman or openapi).
• --name: (Optional) Specify the name of the generated SDK (default: Unnamed).
• --namespace: (Optional) Specify the root namespace for the SDK (default: App\\Sdk).
• --output: (Optional) Specify the output path where the generated code will be created (default: ./Generated).
• --force: (Optional) Force overwriting existing files.
• --dry: (Optional) Perform a dry run. It will not save generated files, only show a list of them.
• --zip: (Optional) Use this flag to generate a zip archive containing all the generated files.

Note: Due to PHP using Backslashes \, when specifying the --namespace, you need to escape any backslashes like so:

Converting Swagger v1 or v2 definitions to the OpenAPI 3.0 format

For convenience, we've included a command that allows you to convert Swagger v1 or v2 definitions to the OpenAPI 3.0 The command will send your api definition file to the Swagger Converter API and save the output in the specified path.

if no output file is specified, the output location will be the original filepath with the .converted.json extension.

To use it, run the following command:

Only OpenAPI is supported for now.

Using the Code Generator and Parser Programmatically

1. Configure Your Generator:

Configure the CodeGenerator with the desired settings:

2. Parse and Generate:

Parse your API specification file and generate the SDK classes:

3. Use Generated Results:

You can access the generated classes and perform actions with them:

How It Works

The Saloon SDK Generator automates the creation of PHP SDKs by following these steps:

1. Parsing API Specifications

The parser reads and understands different API specification formats, including Postman Collection JSON (v2.1), OpenAPI specifications, and custom formats. When executed, it:

• Takes an input file.
• Converts the contents into an internal format called ApiSpecification.
• This format provides a comprehensive view of the API, which the SDK generator uses.

2. Auto-generating SDK Components

This component automatically generates essential SDK components based on parsed specifications:

• Request classes
• Resource classes
• Data Transfer Objects (DTOs)
• Connectors
• Foundational resource class

3. Configurable Generators

The Saloon SDK Generator is modular, allowing you to replace default generators with custom ones to tailor the SDK generation to your needs. The following generators can be customized:

• BaseResourceGenerator
• ConnectorGenerator
• DtoGenerator
• RequestGenerator
• ResourceGenerator

Core Data Structures

These foundational structures form the basis of the generated SDK output:

1. ApiSpecification

• Represents the entire API specification.
• Contains metadata like name, description, base URL, and endpoints catalog.

2. Config

• Central repository for SDK generator configurations.
• Defines namespaces, component suffixes, and other parameters.
• Customizable for specific requirements.

3. Endpoint

• Describes individual API endpoints.
• Includes method types, path segments, and related parameters.

4. GeneratedCode

• Captures the complete generated SDK code.
• Encompasses PHP files for request classes, resource classes, DTOs, connectors, and foundational resource class.

5. Parameter

• Describes parameters associated with API endpoints.
• Includes attributes like type, name, and nullability.

Building a Custom Parser

If you're working with an API specification format that isn't natively supported by the Saloon SDK Generator, you can build a custom parser to integrate it. Here's how you can do it:

1. Create Your Custom Parser:

Start by creating a custom parser class that implements the Crescat\SaloonSdkGenerator\Contracts\Parser interface.

There are two ways to initialize a Parser. The first one is through the constructor, which will receive the filePath specified when running sdkgenerator generate:sdk {FILE_PATH}.

Example:

Or, if you need to pre-process the file, either over the network or run third party code that is not suitable for the constructor, you may add a build method, which will be called instead.

Example from the OpenApiParser:

2. Register Your Custom Parser:

To make your custom parser available in the SDK Generator, you need to register it using the Factory class's registerParser method.

3. Use Your Custom Parser:

Once registered, you can use your custom parser just like any other built-in parser. Specify 'custom' as the --type option when generating the SDK, and the SDK Generator will use your custom parser to process the API specification.

Replace API_SPEC_FILE.xxx with the path to your custom API specification file.

Now your custom parser is seamlessly integrated into the Saloon SDK Generator, allowing you to generate SDKs from API specifications in your custom format.

Swapping Out Default Code Generators

The Saloon SDK Generator is built with flexibility in mind. If you need to customize the generation process for any component of the SDK, you can easily swap out any of the default generators with your own custom implementation.

Implementing a Custom Generator

To create a custom generator:

1. Create a new class that implements the Crescat\SaloonSdkGenerator\Contracts\Generator interface.

   This interface requires two methods:

   • A constructor that accepts a Config object.
   • A generate method that returns either a single PhpFile or an array of PhpFile objects.

Example:

Using Your Custom Generator

Once you've created your custom generator, you can use it by passing an instance of it when creating the CodeGenerator:

By providing your custom generator as an argument to the CodeGenerator, it will be used in place of the default one. This allows for extensive customization of the SDK generation process to suit your specific needs.

Tested with Real API Specifications Samples

To showcase the capabilities of the Saloon SDK Generator and to ensure its compatibility with real-world API specifications, we have tested it with the following API specs.

• Paddle (Not publicly available)
• Stripe ( Postman)
• Tableau ( Postman)
• OpenAI (Postman)
• Fiken (OpenApi)
• GoCardless (OpenApi)
• Tripletex (OpenApi)

Generate SDKs

To generate SDKs from the provided API specs, you can run the following composer scripts:

Generate Zip Archives

If you prefer, (and partially to show that it can do it), you can also generate zip archives of the SDKs:

Feel free to experiment with these commands to see how the Saloon SDK Generator transforms API specifications into PHP SDKs. While these tests provide valuable insights, keep in mind that compatibility may vary depending on the complexity of your specific API specification.

Reporting Incompatibilities

We understand that compatibility issues may arise when using the Saloon SDK Generator with various API specifications. While we welcome reports about these incompatibilities, it's important to note that this tool was initially developed for our internal use and has been open-sourced to share with the community.

If you encounter issues or incompatibilities while generating SDKs from your API specifications, we encourage you to report them on our GitHub Issue Tracker. Your feedback is valuable and can help us improve the tool over time.

However, please understand that due to the nature of the project and our own priorities, we may not always be able to implement immediate fixes for reported issues.

We appreciate your understanding and your interest in using the Saloon SDK Generator. Your contributions, feedback, and reports will contribute to the ongoing development and improvement of this tool for the broader community.

Links and References

• Postman Collection Format
• Postman Collection Format Schema
• Importing and Exporting Data in Postman
• OpenAPI Specification

Building binary

To build the binary for distribution on Packagist, run the following command:

Or use the composer script:

TODOs

• Create configuration (sdkgenerator --config=sdkgenerator.php/json) file that allows you to override behaviour like:
  • what body format to use by default or fallback on
  • ignored parameters,
  • how to handle Pagination
  • if JSON bodies with null values should be removed
  • If you want resource classes or not
  • failure handling (AlwaysThrowOnErrors, custom exception classes, or custom method)
  • etc... (feel free to add suggestions)
• Configurable Conflict Resolver
  • (overwrite (same as --force),
  • new (parse code and only add code that is "new", aka new params, new methods),
  • prompt user for each conflict (like git in interactive mode)
  • etc...
• Generate DTOs based on JSON responses
• When no body can be parsed for POST requests, it should warn the user and add a TODO in the generated code.
• Support older swagger API specification
• Generate tests for all endpoints using Request mocking (see)
• Inject "path" variable in the resource constructor via the connector for clean chaining
  • example: $sdk->resource(userId: 1)->deleteUser();

Contributing

Contributions to this package are welcome! If you find any issues or want to suggest improvements, please submit a pull request or open an issue in the Issue Tracker.

Credits

This package is built on the shoulders of giants, special thanks to the following people for their open source work that helps us all build better software! ❤️

• Nette PHP Generator
• Nuno Maduro for Laravel Zero
• Sam Carré for Saloon

Built by Crescat

Crescat.io is a collaborative software designed for venues, festivals, and event professionals.

With a comprehensive suite of features such as day sheets, checklists, reporting, and crew member booking, Crescat simplifies event management. Professionals in the live event industry trust Crescat to streamline their workflows, reducing the need for multiple tools and outdated spreadsheets.

Troubleshooting:

Fixing command not found errors

You most likely don't have the composer vendor/bin folder in your $PATH

License

The MIT License (MIT). Please see License File for more information.