在PHP中自动记录REST API

Question

phpDocumentor似乎是记录PHP代码的标准,虽然我不知道为什么它多年没有更新..？

但是,它似乎不适合记录REST API的入口点; IE,系统最终用户可能感兴趣的外部可访问入口点,而不是记录所有内部类等 - 这只是api开发人员感兴趣的内容.

我正在寻找我可以说的东西,嘿这个方法可以通过REST在这个URL外部访问,这里是GET或POST参数,它支持GET/POST/etc HTTP方法,它返回JSON或XML等等.

该信息将能够生成API文档.内部代码也可以使用它来自动过滤输入,验证输出,创建基本单元测试等.

Answer 1

我知道3个与swagger的PHP集成:

• Swagger PHP作曲家

• Swagger PHP Symfony包

• Restler 3.0

所有这些都应该有助于自动创建一个swagger-spec,它可以让你从swagger-ui访问.然后你可以生成api客户端等.

Answer 2

RESTful API应完全可发现并自动记录.您只需要一个URL,并且链接到它的所有其他内容都应该描述自己.听起来像乌托邦,但它是可行的.

例如,让我们从类似s​​tackoverflow的示例URL开始:http://restfuloverflow.com(说明性的)

您在RESTful资源上执行的第一件事是OPTIONS请求.您总是需要包含一个Accept标头来指示服务器响应最合适的mime类型:

OPTIONS * HTTP/1.1
Accept: text/html, text/xml, application/json
Host: restfuloverflow.com

服务器应该指示客户端在该URL上可以执行的操作:

HTTP/1.1 200 Ok
Allow: GET, POST, PUT, DELETE, OPTIONS, TRACE, PATCH

这是RESTful API,告诉您此服务支持这些方法.你要尝试的第一个就像下面的请求.使用浏览器访问API的用户应该以类似的方式工作.

GET / HTTP/1.1
Accept: text/html, text/xml, application/json
Host: restfuloverflow.com

然后,服务器应返回一些指向相关资源的链接(如果可用):

HTTP/1.1 200 Ok
Content-Type: text/xml

<?xml version="1.0">
<qa>
    <link href="/questions" title="Questions"/>
    <link href="/tags" title="Tags"/>
    <link href="/users" title="Users"/>
</qa>

HTML版本应使用<a>链接,JSON响应应使用JSON-Schema links属性.

假设客户现在决定它想知道如何处理问题:

OPTIONS /questions HTTP/1.1
Host: restfuloverflow.com
Accept: text/html, text/xml, application/json

可能的回应可能是:

HTTP/1.1 200 Ok
Allow: GET, POST
Content-Type: text/xml

<?xml version="1.0">
<xsd:element name="question">
    <!-- XML Schema describing a question -->
</xsd:element>

好吧,服务器告诉我们可以获取并发布一个新问题.它还通过提供XML Schema告诉我们XML中的问题是怎样的.可以为JSON提供JSON-SCHEMA,并且在HTML中可以提供用于新问题的表单.

假设用户想要获取问题:

GET /questions HTTP/1.1
Host: restfuloverflow.com
Accept: text/html, text/xml, application/json

然后服务器响应:

HTTP/1.1 200 Ok
Content-Type: text/xml

<?xml version="1.0">
<questions>
    <link href="/questions/intersting" title="Intersting Questions"/>
    <link href="/questions/hot" title="Hot Questions"/>
</questions>

现在,一切都再次联系起来.事情继续以服务描述自己的方式进行.在Netflix的API遵循类似的原则,但缺少一些自动发现功能.

这个Brazillian政府API使用RDF描述自己.这是我见过的最好的RESTful样本之一.尝试将.rdf更改为.xml,.json或.html.(这都是葡萄牙语,对不起).

PHP中RESTful API的最佳工具是Respect\Rest.它已经在我已经描述过的大部分工作流程已经引导,并且新功能即将推出(它仍然是0.4x版本).

为RESTful应用程序构建文档系统的成本与构建RESTful应用程序相同.这就是为什么这么少的工具,通常他们不是那么好.

Answer 3

我找到了一个名为apidoc的优秀节点包,它在docful RESTfuls上做了很棒的工作.它允许大量的API特定标签与params和类似的东西一起使用,但真正卖给我的是它为每种方法生成的in-doc测试表单.

我在https://github.com/ardkevin84/devops.skel.php-with-docs-metrics的 devops骨架项目中使用它,但你可以在我的callloop api项目中看到https://github.com的实际输出/ardkevin84/api.callloop.apidoc索引是build/api-docs/apidoc/index.html

唯一的缺点,如果它是一个,它 - 自然 - 采取自己的docblocks.但它并没有与"原生"Docblock冲突.apidoc块不需要在方法之前,因此我通常将它们组合在我的端点文件的顶部,其他doc文档引擎不会将它们与类doc相关联.

副产品:外墙效果很好 ; 我在端点中使用了门面和工厂,而apidoc解析器让我可以单独处理门面条件.在下面的示例中,'subscribe','unsubscribe'和'trigger'由单个入口点处理,但它们是单独记录的.

示例:此Docblocks

/**
 * @api {get} ?action=:action&first=:firstname&last=:lastname&email=:useremail&phone=:phone&gid=:groupid Subscribe
 * @apiSampleRequest http://www.example.com/rest/callloop.php
 * @apiName Subscribe
 * @apiGroup Subscription
 * @apiDescription subscribes a user to the provided group
 * @apiParam {string="subscribe","unsubscribe","trigger"} action=subscribe API Action to call. For subscriptions, use "subscribe"
 * @apiParam {String} [first] Optional first name
 * @apiParam {String} [last] Optional last name
 * @apiParam {String} [email] Optional user email
 * @apiParam {String} phone User's mobile phone number
 */

需要生成此输出,完成测试表单

重要的是,如果您使用带有查询参数的标准$ _GET:从节点安装的软件包不支持类似的连接service.php?param=value,但是在https://github.com/apidoc/apidoc/pull/的git repo中有一个pull请求189解决这个问题.这是默认模板的基本修复.我将几行修补到我的节点包中,它就像一个魅力.

无耻的自我推销:这可能更容易在自动构建下使用.查看我的devops项目以获取kickstart;)它是从jenkins-php派生的,但是添加了几个doc引擎和存根目标,例如将生成的docs\metrics推送到localhost路径并打包输出以用于发布(zip,tar等) )

Answer 4

最简单的事情是使用文档块标记器/解析器。那里有几个（我很快就会插入我的），但基本上他们可以检查文档块并标记任何自定义（或非自定义）文档块标签。我在我的框架中使用它通过名为“@helperType”的标签定义视图助手类型。

就像我说的，有很多，但这是我的，可以帮助您开始： https: //github.com/masterexploder/DocumentingReflectionMethod

基本上，使用类似的东西，您可以使用它来生成文档，并执行自动过滤、验证等操作。

至于单元测试创​​建，PHPUnit 可以从您的类自动生成这些单元测试（查看他们的文档以获取更多信息：http://www.phpunit.de/manual/3.5/en/sculpture-generator.html#sculpture-generator.test

您还可以让 phpdocumenter 解析您的自定义标签：http://manual.phpdoc.org/HTMLSmartyConverter/default/phpDocumentor/tutorial_phpDocumentor.howto.pkg.html#using.command-line.customtags

最后，有一个框架（据我所知，我确信有很多）可以使用注释来完成各种令人安心的事情（也许可以为自己节省一些工作）： https: //github.com/recess/课间休息

希望有帮助！