README

创建一个库，用于从类似Guzzle的服务描述中消费API。

为什么？

编写一个用于消费HTTP API的服务不是一件有趣的事情。不是需要为API中的每个操作编写大量繁琐的样板代码，就是编写通用的方法来丢失所有类型信息。

不仅最初编写库不是一件有趣的事情，而且在HTTP API提供商添加方法或微妙地更改现有方法时维护它也很繁琐。

如果能够简单地定义一个操作

    "addUserEmails" => array(
        "uri" => "https://api.github.com/user/emails",
        'extends' => 'defaultOauthOperation',
        'summary' => 'Get users email addresses',
        'scopes' => [
            [\ArtaxApiBuilder\Service\Github::SCOPE_USER],
        ],
        'responseClass' => 'Github\Emails',
        'httpMethod' =>  'POST',
        'parameters' => array(
            'emails' => array(
                "location" => "json",
                "description" => "Array of the emails to add",
            ),
        ),
    ),

然后所有服务代码都生成并可用于这样

    $api = new GithubAPI(GITHUB_USER_AGENT);
    $emailCommand = $api->addUserEmails(
        $accessToken,
        [$newEmail1, $newEmail2]
    );
    
    $currentEmails = $emailCommand->execute();
    
    //The execute function has a docblock return type of 
    //@return \Github\Emails
    foreach ($currentEmails as $email) {
        printf("Address %s verified %s primary %s ",
            $email->address,
            $email->verified,
            $email->primary
        );
    ]

为什么不使用Guzzle服务？

• Curl/PHP流的底层HTTP实现并不出色。

• 仍然有一个庞大的代码库，实际上并没有做太多。

• 不可测试/不可模拟。

• 代码生成的服务允许您根据需要调试、扩展或修改代码。一旦代码生成，它就存在并且可以完全修改（如果您愿意），而不是要求所有内容都通过Guzzle进行。

• 使用生成的服务需要更小的内存需求（内存是PHP的阿喀琉斯之踵）。

• 为伟大的正义而进行所有类型提示。

• 更好地暴露底层机制。尽管Guzzle为您做了一切，但直接访问请求和/或响应是当人们搞砸API时的一种相当强大的技术，您需要绕过他们的愚蠢（GitHub，我在看着你）。

待办事项

• errorResponses - 目前几乎没有错误处理。能够在API级别定义这将是件好事，而不是不得不编写支持它的代码。

• 意外的响应作为错误或异常 - 实际上，这个库将不得不支持两者，因为有些情况下异常是正确的，而在其他情况下检查响应类类型将是正确的。

• filters - 是的，将需要变量过滤器。目前只有一个翻译过滤器。

• includes - 这不是世界上最重要的事情，但能够将服务描述分割成可管理的块将会很棒。

• apiVersion - 是的。需要一些API版本控制。

• 需要读取速率限制头并使该信息通过API类可用。

• 缓存响应+存储/使用ETags/最后修改等，以避免提前触发速率限制。

未实现

• additionalParameters - 明确的参数（$foo->setBar($bar)）比基于信仰的参数（$foo->setParams(['bar' => $bar]);）要好得多，因此它们不受支持。

• responseModel - 我没有使用过它，并且并不特别喜欢它的想法，因为似乎有更好的（或者至少松散耦合的）方法将响应转换为对象。

• responseBody - 当您控制请求时，这并不是必要的。

Danack/Code 与 Zend/Code 的比较

请注意，分支 Danack/Code 几乎与 Zend/Code 完全相同，只是它包含了一些仅在 Zend/Code 下一个主要版本中发布的错误修复。由于在可预见的未来不会发生这种情况，这个库目前使用了我添加了修复的分支。计划是在下一个主要版本时回归到 Zend/Code 的主流版本。