README

Saloon SDK 生成器 - 简化 SDK 框架 🚀

介绍 Saloon SDK 生成器 - 使用强大的 Saloon 包快速创建 PHP SDK 基础结构的工具。

请注意：此工具帮助您搭建 SDK 的基础，但可能不会创建一个完整、可直接使用的解决方案。🛠️

无论您使用的是 Postman Collection JSON 文件（v2.1）还是 OpenAPI 规范，Saloon SDK 生成器都简化了生成 PHP SDK 的过程。它为您提供构建 API 交互初始框架的起点。

请记住，生成的代码可能并不适用于所有情况。将其视为快速搭建 SDK 结构的方法。虽然您可能需要针对特定情况进行定制，但 Saloon SDK 生成器通过消除从头创建样板代码的需要来节省您的时间。

您的定制 SDK 之旅从这里开始 - 使用 Saloon SDK 生成器。🌟

安装

您可以使用 Composer 安装此包

composer global require crescat-io/saloon-sdk-generator

用法

要从 API 规范文件生成 PHP SDK，请运行以下命令

sdkgenerator generate:sdk API_SPEC_FILE.{json|yaml|yml}
     --type={postman|openapi}
    [--name=SDK_NAME]
    [--output=OUTPUT_PATH]
    [--namespace=Company\\Integration]
    [--force]
    [--dry]
    [--zip]

将占位符替换为相应的值

API_SPEC_FILE：API 规范文件（JSON 或 YAML 格式）的路径。
--type：指定 API 规范类型（postman 或 openapi）。
--name：（可选）指定生成的 SDK 名称（默认：Unnamed）。
--namespace：（可选）指定 SDK 的根命名空间（默认：App\\Sdk）。
--output：（可选）指定生成代码的输出路径（默认：./Generated）。
--force：（可选）强制覆盖现有文件。
--dry：（可选）执行干运行。它不会保存生成的文件，只会显示它们的列表。
--zip：（可选）使用此标志生成包含所有生成文件的 zip 存档。

注意：由于 PHP 使用反斜杠 \，在指定 --namespace 时，您需要将任何反斜杠转义，如下所示

sdkgenerator generate:sdk ./tests/Samples/paddle.json
  --force
  --type=postman
  --name=Paddle
  --output ./paddle-sdk/src
  --namespace=Your\\Sdk\\Namespace # <-- Note the "\\"

程序化使用代码生成器和解析器

配置您的生成器

使用所需设置配置 CodeGenerator

$generator = new CodeGenerator(
   namespace: "App\Sdk",
   resourceNamespaceSuffix: 'Resource',
   requestNamespaceSuffix: 'Requests',
   dtoNamespaceSuffix: 'Dto',
   connectorName: 'MySDK', // Replace with your desired SDK name
   outputFolder: './Generated', // Replace with your desired output folder
   ignoredQueryParams: ['after', 'order_by', 'per_page'] // Ignore params used for pagination
);

解析和生成

解析您的 API 规范文件并生成 SDK 类

$inputPath = 'path/to/api_spec_file.json'; // Replace with your API specification file path
$type = 'postman'; // Replace with your API specification type

$result = $generator->run(Factory::parse($type, $inputPath));

使用生成的结果

您可以通过访问生成的类并使用它们来执行操作

// Generated Connector Class
echo "Generated Connector Class: " . Utils::formatNamespaceAndClass($result->connectorClass) . "\n";

// Generated Base Resource Class
echo "Generated Base Resource Class: " . Utils::formatNamespaceAndClass($result->resourceBaseClass) . "\n";

// Generated Resource Classes
foreach ($result->resourceClasses as $resourceClass) {
   echo "Generated Resource Class: " . Utils::formatNamespaceAndClass($resourceClass) . "\n";
}

// Generated Request Classes
foreach ($result->requestClasses as $requestClass) {
   echo "Generated Request Class: " . Utils::formatNamespaceAndClass($requestClass) . "\n";
}

工作原理

Saloon SDK 生成器通过以下步骤自动化创建 PHP SDK：

1. 解析 API 规范

解析器读取并理解不同的 API 规范格式，包括 Postman Collection JSON（v2.1）、OpenAPI 规范和自定义格式。当执行时，它

读取输入文件。
将内容转换为名为 ApiSpecification 的内部格式。
该格式提供对 API 的全面视图，SDK 生成器使用该视图。

2. 自动生成 SDK 组件

此组件根据解析的规范自动生成基本 SDK 组件

请求类
资源类
数据传输对象（DTOs）
连接器
基础资源类

3. 可配置的生成器

Saloon SDK 生成器是模块化的，允许您用自定义生成器替换默认生成器，以便根据您的需求定制 SDK 生成。以下生成器可以进行自定义

BaseResourceGenerator
ConnectorGenerator
DtoGenerator
请求生成器
资源生成器

核心数据结构

这些基础结构构成了生成的SDK输出的基础。

1. ApiSpecification

代表整个API规范。
包含诸如名称、描述、基础URL和端点目录之类的元数据。

2. Config

SDK生成器配置的中央存储库。
定义命名空间、组件后缀和其他参数。
可根据特定要求进行自定义。

3. Endpoint

描述单个API端点。
包括方法类型、路径段和相关参数。

4. GeneratedCode

捕获完整的生成SDK代码。
包括请求类、资源类、DTO、连接器和基础资源类的PHP文件。

5. Parameter

描述与API端点关联的参数。
包括类型、名称和可空性等属性。

构建自定义解析器

如果您正在使用Saloon SDK生成器不支持的本机API规范格式，您可以构建一个自定义解析器来集成它。以下是您可以这样做的步骤：

创建您的自定义解析器

首先，创建一个自定义解析器类，该类实现了Crescat\SaloonSdkGenerator\Contracts\Parser接口。

初始化解析器有两种方式。第一种是通过构造函数，它将在运行sdkgenerator generate:sdk {FILE_PATH}时接收指定的filePath。

示例

<?php

namespace YourNamespace\CustomParser;

use Crescat\SaloonSdkGenerator\Contracts\Parser;
use Crescat\SaloonSdkGenerator\Data\Generator\Endpoint;
use Crescat\SaloonSdkGenerator\Data\Generator\ApiSpecification;
use Crescat\SaloonSdkGenerator\Data\Generator\Parameter;

class CustomParser implements Parser
{
    public function __construct(protected $filePath) {}

    public function parse(): ApiSpecification
    {
        // TODO: Implement
        parseTheContents($this->filepath)
        // Implement a parser that will return an ApiSpecification object:

        return new ApiSpecification(
            name: 'Custom API',
            description: 'A custom API specification',
            baseUrl: 'https://api.example.com',
            endpoints: [
                new Endpoint(
                    name: 'GetUserInfo',
                    method: 'GET',
                    pathSegments: ['users', '{user_id}'],
                    description: 'Get user information by ID',
                    queryParameters: [
                        new Parameter('string', false, 'user_id', 'User ID'),
                    ],
                ), new Endpoint(
                    name: 'CreateUser',
                    method: 'POST',
                    pathSegments: ['users'],
                    description: 'Create a new user',
                    bodyParameters: [
                        new Parameter('string', false, 'username', 'Username'),
                        new Parameter('string', false, 'email', 'Email'),
                    ],

                )
            ],
        );
    }
}

或者，如果您需要预处理文件，无论是通过网络还是运行不适合构造函数的第三方代码，您可以添加一个build方法，它将代替调用。

来自OpenApiParser的示例

public static function build($content): static
{
    // Call file readers depending on the filetype provided (supports JSON and YAML)
    return new static(
        Str::endsWith($content, '.json')
            ? Reader::readFromJsonFile(fileName: realpath($content), resolveReferences: ReferenceContext::RESOLVE_MODE_ALL)
            : Reader::readFromYamlFile(fileName: realpath($content), resolveReferences: ReferenceContext::RESOLVE_MODE_ALL)
    );
}

注册您的自定义解析器

要使您的自定义解析器在SDK生成器中可用，您需要使用Factory类的registerParser方法进行注册。

use Crescat\SaloonSdkGenerator\Factory;
use YourNamespace\CustomParser;
// Replace with the actual namespace of your custom parser

// Register your custom parser
Factory::registerParser('custom', CustomParser::class);

使用您的自定义解析器

一旦注册，您就可以像使用任何其他内置解析器一样使用您的自定义解析器。在生成SDK时指定'custom'作为--type选项，SDK生成器将使用您的自定义解析器来处理API规范。

sdkgenerator generate:sdk API_SPEC_FILE.xxx --type=custom

将API_SPEC_FILE.xxx替换为您自定义API规范文件的路径。

现在，您的自定义解析器已无缝集成到Saloon SDK生成器中，允许您从自定义格式的API规范生成SDK。

替换默认代码生成器

Saloon SDK生成器在设计时考虑了灵活性。如果您需要自定义SDK的任何组件的生成过程，您可以轻松地将任何默认生成器替换为您的自定义实现。

实现自定义生成器

要创建自定义生成器

创建一个新的类，该类实现了Crescat\SaloonSdkGenerator\Contracts\Generator接口。

此接口需要两个方法
- 一个接受Config对象的构造函数。
- 一个返回单个PhpFile或PhpFile对象数组的generate方法。

示例

namespace YourNamespace;

use Crescat\SaloonSdkGenerator\Contracts\Generator;
use Crescat\SaloonSdkGenerator\Data\Generator\ApiSpecification;
use Crescat\SaloonSdkGenerator\Data\Generator\Config;
use Nette\PhpGenerator\PhpFile;

class CustomRequestGenerator implements Generator
{
    public function __construct(Config $config)
    {
        // Initialize your generator with the configuration
    }

    public function generate(ApiSpecification $specification): PhpFile|array
    {
        // Your custom generation logic here
    }
}

使用您的自定义生成器

一旦创建了您的自定义生成器，您可以在创建CodeGenerator时传递其实例来使用它。

$customRequestGenerator = new CustomRequestGenerator($config);

$codeGenerator = new CodeGenerator(
    config: $config,
    requestGenerator: $customRequestGenerator
    // ... you can pass other custom generators as needed
);

$result = $codeGenerator->run($specification);

通过将自定义生成器作为参数提供给CodeGenerator，它将替换默认生成器。这允许对SDK生成过程进行广泛的定制，以满足您的特定需求。

已与真实API规范样本进行测试

为了展示Saloon SDK生成器的功能并确保其与真实世界的API规范兼容性，我们已使用以下API规范进行了测试。

Paddle (不公开可用)
Stripe ( Postman)
Tableau ( Postman)
OpenAI (Postman)
Fiken (OpenApi)
GoCardless (OpenApi)
Tripletex (OpenApi)

生成SDK

要从提供的API规范中生成SDK，您可以运行以下composer脚本

composer generate:paddle
composer generate:stripe
composer generate:tableau
composer generate:openai
composer generate:fiken
composer generate:gocardless
composer generate:tripletex

生成ZIP存档

如果您愿意，并且部分是为了展示它可以做到这一点），您还可以生成SDK的ZIP存档

composer generate:zip:paddle
composer generate:zip:stripe
composer generate:zip:tableau
composer generate:zip:openai
composer generate:zip:fiken
composer generate:zip:gocardless
composer generate:zip:tripletex

请随意尝试这些命令，以了解Saloon SDK生成器如何将API规范转换为PHP SDK。虽然这些测试提供了有价值的见解，但请注意，兼容性可能因您特定API规范的复杂性而有所不同。

报告不兼容性

我们理解，当使用Saloon SDK生成器与各种API规范时可能会出现兼容性问题。虽然我们欢迎关于这些不兼容性的报告，但重要的是要指出，这个工具最初是为我们内部使用而开发的，并且已经开源以与社区分享。

如果您在从您的API规范生成SDK时遇到问题或不兼容性，我们鼓励您在我们的GitHub问题跟踪器上报告它们。您的反馈非常有价值，可以帮助我们在未来改进此工具。

然而，请理解，由于项目性质和我们的优先事项，我们可能无法始终立即修复报告的问题。

我们感谢您的理解和对使用Saloon SDK生成器的兴趣。您的贡献、反馈和报告将有助于推动这个工具的持续发展和改进，以造福更广泛的社区。

链接和参考

构建二进制文件

要为Packagist上的分发构建二进制文件，请运行以下命令

php ./builds/sdkgenerator app:build sdkgenerator --build-version=1.0

或使用composer脚本

composer build

待办事项

创建配置（sdkgenerator --config=sdkgenerator.php/json）文件，允许您覆盖行为，例如
- 默认或回退使用的正文格式
- 忽略参数
- 如何处理分页
- 是否应该删除带有null值的JSON正文
- 是否需要资源类
- 失败处理（AlwaysThrowOnErrors、自定义异常类或自定义方法）
- 等等...（请随意提出建议）
可配置的冲突解决器
- （覆盖（与--force相同），
- 新（解析代码并仅添加“新”代码，即新参数、新方法），
- 提示用户处理每个冲突（类似于git的交互模式）
- 等等...
根据JSON响应生成DTO
当无法解析POST请求的正文时，应警告用户并在生成的代码中添加TODO。
支持旧版swagger API规范
使用请求模拟为所有端点生成测试（查看）
通过连接器在资源构造函数中注入“路径”变量以实现干净的链式调用
- 示例： $sdk->resource(userId: 1)->deleteUser();

贡献

欢迎对此包做出贡献！如果您发现任何问题或想提出改进建议，请提交拉取请求或在问题跟踪器中打开一个问题。

鸣谢

本包建立在巨人的肩膀之上，特别感谢以下人员对开源工作的贡献，他们的工作帮助我们所有人构建更好的软件！❤️

由 Crescat 构建

Crescat.io 是一款专为场地、音乐节和活动专业人士设计的协作软件。

Crescat 提供了一套全面的功能，如日程表、清单、报告和团队成员预订，简化了活动管理。现场活动行业的专业人士信任 Crescat 流程化他们的工作流程，减少了对多个工具和过时电子表格的需求。

故障排除

修复 `未找到命令` 错误

您可能没有在您的 $PATH 中找到 composer 的 vendor/bin 文件夹

# Default config file paths
# Zsh:   ~/.zshrc
# Bash:  ~/.bashrc or ~/.bash_profile
# Fish:  ~/.config/fish/config.fish

# Replace 'YOUR_USERNAME' with your actual username
# Example: '/Users/john/.composer/vendor/bin'

# Zsh
echo 'export PATH="/Users/YOUR_USERNAME/.composer/vendor/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

# Bash
echo 'export PATH="/Users/YOUR_USERNAME/.composer/vendor/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

# Fish
echo 'set -gx PATH "/Users/YOUR_USERNAME/.composer/vendor/bin" $PATH' >> ~/.config/fish/config.fish
source ~/.config/fish/config.fish

许可协议

MIT 许可协议（MIT）。有关更多信息，请参阅许可文件。

abishekrsrikaanth / saloon-sdk-generator

维护者

详细信息

README

Saloon SDK 生成器 - 简化 SDK 框架 🚀

安装

用法

程序化使用代码生成器和解析器

工作原理

1. 解析 API 规范

2. 自动生成 SDK 组件

3. 可配置的生成器

核心数据结构

1. ApiSpecification

2. Config

3. Endpoint

4. GeneratedCode

5. Parameter

构建自定义解析器

替换默认代码生成器

实现自定义生成器

使用您的自定义生成器

已与真实API规范样本进行测试

生成SDK

生成ZIP存档

报告不兼容性

链接和参考

构建二进制文件

待办事项

贡献

鸣谢

由 Crescat 构建

故障排除

修复 `未找到命令` 错误

许可协议

abishekrsrikaanth / saloon-sdk-generator

维护者

详细信息

README

Saloon SDK 生成器 - 简化 SDK 框架 🚀

安装

用法

程序化使用代码生成器和解析器

工作原理

1. 解析 API 规范

2. 自动生成 SDK 组件

3. 可配置的生成器

核心数据结构

1. ApiSpecification

2. Config

3. Endpoint

4. GeneratedCode

5. Parameter

构建自定义解析器

替换默认代码生成器

实现自定义生成器

使用您的自定义生成器

已与真实API规范样本进行测试

生成SDK

生成ZIP存档

报告不兼容性

链接和参考

构建二进制文件

待办事项

贡献

鸣谢

由 Crescat 构建

故障排除

修复 未找到命令 错误

许可协议

修复 `未找到命令` 错误