README

通过从 Open API 规范生成大部分代码，简化客户端的创建。

使用 Elastic OpenAPI PHP 客户端生成器的项目

• Elastic Site Search 官方 PHP 客户端
• Elastic App Search 官方 PHP 客户端

内容

• 入门指南
• 使用客户端
• 常见问题解答
• 贡献
• 许可

使用生成器入门 🐣

要求

我们假设您已经安装并可以在您的环境中使用以下组件

• Docker（用于运行代码生成器）
• composer

初始化项目

当您想要创建一个新的客户端时，您首先需要创建一个新的 composer 项目。

composer create-project my-new-fancy-client

一旦项目创建完成，您应该更新您的 composer.json 文件（包名、作者等）。确保自动加载部分包含您想要用于客户端的 PHP 命名空间（这里为 Fancy\Client）

"autoload": {
  "psr-4": {
    "Fancy\\Client\\": ""
  }
}

一旦项目创建完成，您必须将代码生成器作为项目的需求添加

composer require elastic/openapi-codegen

配置生成器

按照惯例，代码生成器期望 resources/api 文件夹包含两个文件

• api-spec.yml：描述服务器 API 的 OpenAPI 规范。您可以在以下位置找到完整功能的示例：https://github.com/swiftype/swiftype-site-search-php/blob/master/resources/api/api-spec.yml

• config.json：一个包含重要变量变量的配置文件，允许配置代码和文档生成

{
    "gitUserId": "myorg",
    "gitRepoId": "my-new-fancy-client",
    "artifactVersion": "1.0.0",
    "invokerPackage": "Fancy\\Client",
    "helpUrl": "https://discuss.elastic.co/c/site-search",
    "copyright": "© [Elastic](https://github.com/elastic)"
}

运行生成器

一旦项目设置完成并配置了生成器，您可以通过使用项目根目录中的启动脚本来运行代码生成

vendor/bin/elastic-openapi-codegen.sh

生成器将在您的项目中创建或更新以下文件

• Client.php：包含您规范中每个路径/操作的每个方法客户端类。

• Endpoint/*.php：每个路径/操作的规范都有一个端点类。

• README.md：您的项目的 Readme（有关自定义文档的说明，请参阅此处）

创建客户端构建器

客户端实例化逻辑对于每个项目都是特定的，需要为每个项目定制（认证管理、错误处理）。同时，您的客户端的最终用户期望有一个非常简单易用的方法来实例化客户端。

以下是为最终用户提供非常基本的客户端构建器的代码

namespace Fancy\Client;

class ClientBuilder extends \Elastic\OpenApi\Codegen\AbstractClientBuilder
{
    /**
     * Return the configured client.
     *
     * @return \Fancy\Client\Client
     */
    public function build()
    {
        return new Client($this->getEndpointBuilder(), $this->connection());
    }

    /**
     * Endpoint builder is in charge of resolving the endpoint classes.
     * Need to be configured with your own namespace.
     */
    protected function getEndpointBuilder()
    {
        return new \Elastic\OpenApi\Codegen\Endpoint\Builder(__NAMESPACE__ . '\Endpoint');
    }
}

使用客户端

一旦完成上述任务，最终用户就可以非常容易地获取到他们可以使用的客户端

$clientBuilder = new \Fancy\Client\ClientBuilder();
$client = $clientBuilder->build();

定制

现在您有一个正在运行的客户端，您可能想要定制几个东西

• 客户端和端点代码生成
• 文档生成
• 连接逻辑：请求和响应处理、认证等

您可以在定制文档中找到可用扩展点的完整文档。

常见问题解答 🔮

我在哪里报告客户端的问题？

如果某些东西没有按预期工作，请打开一个问题。

贡献 🚀

我们欢迎对项目做出贡献的贡献者。在您开始之前，请注意以下几点...

• 在提交拉取请求之前，请创建一个议题来讨论您提案的范围。
• 当适用时，请编写简洁的代码和文档。

许可证 📗

Apache 2.0 © Elastic

感谢所有贡献者！