silverstripe-terraformers / openapi-codegen-php-8
用于创建 Elastic PHP 客户端的基库。
Requires
- php: >=5.6
- guzzlehttp/ringphp: ^1.0
- psr/log: ^1.0.
Requires (Dev)
- friendsofphp/php-cs-fixer: ^2.14
- overtrue/phplint: ^1.1
- phpmd/phpmd: ^2.6
- phpunit/phpunit: ^5.6.0|^6.3.0
- squizlabs/php_codesniffer: ^3.4.0
README
⚠️ 此客户端已弃用 ⚠️
此包仅用于作为允许 PHP 8 作为平台要求的 Elastic OpenAPI PHP 客户端生成器的服务
所有赞誉和荣誉归功于 Elastic OpenAPI PHP 客户端生成器的贡献者
Elastic OpenAPI PHP 客户端生成器。
通过从 Open API 规范生成大部分代码来简化客户端的创建。
使用 Elastic OpenAPI 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();
定制
现在您有一个工作的客户端,有一些事情您可能想要进行定制。
- 客户端和端点代码生成
- 文档生成
- 连接逻辑:请求和响应处理、身份验证...
您可以在定制文档中找到所有可用扩展点的完整文档。
常见问题解答 🔮
我在哪里报告客户端的问题?
如果某件事没有按预期工作,请打开一个问题。
贡献 🚀
我们欢迎对项目做出贡献。在您开始之前,请注意以下几点...
- 在打开拉取请求之前,请创建一个问题来讨论您建议的范围。
- 当适用时,请编写简单的代码和简洁的文档。
许可 📗
感谢所有贡献者!