使用PHP自动文档化REST API

Question

phpDocumentor似乎是记录PHP代码的标准，但我想知道为什么它多年来都没有更新..?

然而，它似乎不适合记录REST API的入口点; 即外部可访问的入口点，这些入口点可能是系统的最终用户感兴趣的，与记录所有内部类等内容无关 - 这只对API开发人员有利。

我正在寻找一种方法，在其中可以说明：这里的这种方法可以通过REST在此URL上外部访问，它接受GET或POST参数，支持GET / POST /等HTTP方法，返回JSON或XML或其他格式的数据。

此信息将能够生成API文档。 它还可以被内部代码用于自动过滤输入，验证输出，创建基本单元测试等等。

- Greywire

---

与这个和那个有关，尽管后者似乎重复了前者。 - Patrick

Answer 1

我知道三种与Swagger相关的PHP集成方式：

• Swagger PHP composer

• Swagger PHP Symfony bundle

• Restler 3.0

它们都可以帮助自动创建Swagger规范，以便从Swagger-UI访问。然后，您就可以生成API客户端等。

- fehguy

---

如果使用Symfony 2.x，还应该检查Nelmio API Doc Bundle：https://github.com/nelmio/NelmioApiDocBundle - Nikola Petkanski

我使用Swagger PHP（从Composer）来记录我们的工作API http://api.buto.tv/docs。效果非常好。 - Jujhar Singh

Answer 2

一种RESTful API应该是完全可发现和自动文档化的。您只需要一个URL，其余链接应该自我描述。听起来像是理想状态，但这是可行的。

例如，让我们以类似stackoverflow的示例URL为起点：http://restfuloverflow.com（仅供说明）

在RESTful资源上，您首先要做的是OPTIONS请求。您始终需要包含一个Accept header来指示服务器响应最适合的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>

服务器告诉我们可以使用GET和POST提交一个新的问题。它还通过提供XML Schema来告诉我们问题长什么样子。针对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 遵循类似的原则，但缺乏一些自动发现功能。

这个巴西政府 API 使用 RDF 描述自己。这是我见过的最好的 RESTful 示例之一。尝试将 .rdf 更改为 .xml、.json 或 .html。（所有内容都是葡萄牙语的，对此抱歉）。

PHP 中最好的 RESTful API 工具是 Respect\Rest。它已经预设了我在这里描述的大部分工作流程，并且正在推出新功能（目前还处于 0.4x 版本）。

构建 RESTful 应用程序的文档系统的成本与构建 RESTful 应用程序的成本相同。这就是为什么像这样的工具很少，而且通常不那么好的原因。

- alganet

---

我投了反对票(-1)。原因很简单——问题是如何记录通过RESTful服务暴露的API的行为，而不是如何构建REST服务。目前我需要这样的解决方案，而这个答案对我没有任何帮助。 - Nikola Petkanski

这个问题是关于自动文档化的，意思是能够自行生成软件文档。为此需要保证结构的一致性。即使只部分实现（大多数 REST 服务不会实现OPTIONS），也仍然可以获得自动文档化的好处。我不知道有哪些通用的外部工具可用于文档化通用的 REST 服务。 - alganet

这段话的意思是：这并没有回答问题。问题并没有排除自动发现的 REST API。问题是关于自动生成文档的生成。即使是可自动发现的，您仍然需要一些相当数量的文档来了解API实现的功能以及如何解释数据，以便能够遵循链接。在restfuloverflow的示例中 - 开发人员想要添加自动评论。但是如果不知道“评论”是什么资源，那就无法完成它。文本“添加评论”并没有告诉代码它的含义。 - Petter Nordlander

另一个将此答案评为-1的原因是您正在谈论基于HATEOAS的ReST服务。ReST是一种设计模式，而HATEOAS是ReST的一个极其严格的版本，具有许多头部集成、自动发现等功能。不要混淆ReST和HATEOAS，因为它们可以相互独立存在！ - Mathieu Dumoulin

Answer 3

我发现了一个很棒的Node.js包，名为apidoc，它非常擅长对RESTful API进行文档化。它允许使用许多与参数等API特定标签相关的功能，但真正吸引我的是它为每个方法生成的文档测试表单。

我在我的DevOps骨架项目中使用它，地址为https://github.com/ardkevin84/devops.skel.php-with-docs-metrics，但您可以在我的callloop API项目中查看实际输出，地址为https://github.com/ardkevin84/api.callloop。apidoc索引位于build/api-docs/apidoc/index.html。

唯一的缺点是——很自然地——它采用了独立的docblocks。不过它不会与“本机”Docblock冲突。apidoc块不需要放在方法之前，因此我通常会将它们分组放在端点文件的顶部，在那里其他文档引擎不会将它们与类文档关联起来。

一个副作用是这可以与facade非常好地配合使用。在我的端点中，我经常使用facade和factory，apidoc解析器让我可以单独处理facade条件。在下面的示例中，“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/189 的 git 存储库中有一个拉请求来解决这个问题。它是对默认模板的基本修复。我将这个修补程序打入我的节点软件包中，效果非常好。

厚颜无耻的自我推广：这可能更容易在自动化构建下使用。请查看上面的 devops 项目以获取启动；）它是从 jenkins-php 派生出来的，但添加了几个文档引擎和存根目标，用于将生成的文档\指标推送到 localhost 路径并为发布打包输出（zip、tar 等等）。

- Kevin Ard

Answer 4

Swagger看起来很有前途，但它需要您的API以兼容的方式公开自己... 它非常好用，内置了测试控制台等功能... 您可以下载JavaScript版本并在php API旁边在服务器上运行。

编辑：这是链接，如果没有完整名称，在谷歌上找到它并不容易... 哈哈... Swagger-UI: https://github.com/wordnik/swagger-ui

- RVN

Answer 5

最简单的方法是使用docblock分词器/解析器。有几个这样的工具（我很快会介绍我的），但基本上它们可以检查docblock并标记任何自定义（或非自定义）的docblock标签。我在我的框架中使用了一个名为“@helperType”的标签来定义视图助手类型。

就像我说的，有很多这样的工具，但以下是我的工具，可以帮助你入门：https://github.com/masterexploder/DocumentingReflectionMethod 基本上，使用类似于这样的工具，你可以用它来生成文档，并执行自动过滤、验证等操作。

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

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

最后，有一个框架（我知道的，肯定还有很多）使用注释来执行各种RESTful操作（也许可以节省一些工作）：https://github.com/recess/recess

希望对您有所帮助！

- Ian Selby

---

也许你想看看 Vanity Docs（我的朋友正在开发它）。尚未发布，但应该很快：http://twitter.com/#!/vanitydoc - Ian Selby

我实际上见过Recess框架，它看起来很不错。现在我一直在使用Kohana。 - Greywire

我已经在数据库操作和一些验证方面使用了注释（通过Addendum）。我曾考虑过基于我已有的东西来编写自己的文档生成器，但我想肯定已经有人为文档化REST Web服务做过这件事了。至于测试，也许单元测试不是正确的术语，但功能测试可能更合适。例如测试REST API而不是测试单个类。我记得曾经看过phpdocumentor中的自定义标签，但它似乎很难使用，也许我会重新考虑一下（我想知道为什么这么长时间没有更新？） - Greywire

最后，我一定会查看你的东西。 :) - Greywire