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->getConnection());
    }

    /**
     * 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();

自定义

现在您有一个工作的客户端，有一些事情您可能想要自定义

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

您可以在自定义文档中找到有关可用的扩展点的完整文档。

常见问题解答 🔮

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

如果某些事情没有按预期工作，请打开问题。

贡献 🚀

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

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

许可 📖

感谢所有贡献者！

elastic / openapi-codegen

维护者

详细信息