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

用法

从 OpenAPI 或 Postman 集合生成 SDK

要从 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：（可选）进行 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 "\\"

将 Swagger v1 或 v2 定义转换为 OpenAPI 3.0 格式

为了方便，我们包括了一个命令，允许您将 Swagger v1 或 v2 定义转换为 OpenAPI 3.0。该命令会将您的 api 定义文件发送到 Swagger Converter API 并将输出保存到指定的路径。

如果没有指定输出文件，输出位置将是原始文件路径，并带有 .converted.json 扩展名。

要使用它，请运行以下命令

sdkgenerator convert old.json [output.json]

## e.g.
sdkgenerator convert tests/Samples/tripletex.json tests/Samples/tripletex.converted.json

目前仅支持 OpenAPI。

以编程方式使用代码生成器和解析器

配置您的生成器

使用所需设置配置 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
RequestGenerator
ResourceGenerator

核心数据结构

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

1. ApiSpecification

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

2. Config

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

3. Endpoint

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

4. GeneratedCode

捕获完整的生成 SDK 代码。
包括请求类、资源类、DTOs、连接器和基础资源类的 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): self
{
    // Call file readers depending on the filetype provided (supports JSON and YAML)
    return new self(
        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

TODOs

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

贡献

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

致谢

此包建立在巨人的肩膀上，特别感谢以下人士对开源工作的贡献，他们的贡献帮助我们都能够构建更好的软件！❤️

Built by 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）。请参阅许可证文件以获取更多信息。

crescat-io / saloon-sdk-generator

维护者

详细信息

README

Saloon SDK 生成器 - 简化 SDK 脚手架 🚀

安装

用法

从 OpenAPI 或 Postman 集合生成 SDK

将 Swagger v1 或 v2 定义转换为 OpenAPI 3.0 格式

以编程方式使用代码生成器和解析器

工作原理

1. 解析 API 规范

2. 自动生成 SDK 组件

3. 可配置的生成器

核心数据结构

1. ApiSpecification

2. Config

3. Endpoint

4. GeneratedCode

5. Parameter

构建自定义解析器

替换默认代码生成器

实现自定义生成器

使用您自定义的生成器

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

生成SDK

生成ZIP存档

报告不兼容性

链接和参考

构建二进制文件

TODOs

贡献

致谢

Built by Crescat

故障排除

修复`命令未找到`错误

许可证

crescat-io / saloon-sdk-generator

维护者

详细信息

README

Saloon SDK 生成器 - 简化 SDK 脚手架 🚀

安装

用法

从 OpenAPI 或 Postman 集合生成 SDK

将 Swagger v1 或 v2 定义转换为 OpenAPI 3.0 格式

以编程方式使用代码生成器和解析器

工作原理

1. 解析 API 规范

2. 自动生成 SDK 组件

3. 可配置的生成器

核心数据结构

1. ApiSpecification

2. Config

3. Endpoint

4. GeneratedCode

5. Parameter

构建自定义解析器

替换默认代码生成器

实现自定义生成器

使用您自定义的生成器

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

生成SDK

生成ZIP存档

报告不兼容性

链接和参考

构建二进制文件

TODOs

贡献

致谢

Built by Crescat

故障排除

修复命令未找到错误

许可证

修复`命令未找到`错误