在 PHP 中自动记录 REST API

php rest documentation-generation

2022-08-30 17:44:38

phpDocumentor似乎是记录PHP代码的标准，尽管我不得不怀疑为什么它已经多年没有更新了..？

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

我正在寻找一些我可以说的东西，嘿，这里的这个方法可以通过这个URL的REST从外部访问，这是它需要的GET或POST参数，它支持GET / POST / etc HTTP方法，它返回JSON或XML或其他任何东西。

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

答案 1

我知道3 PHP与swagger集成：

所有这些都应该有助于自动创建一个swagger-spec，它允许您从swagger-ui访问。然后，您可以生成 API 客户端等。

答案 2

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

例如，让我们从一个类似堆栈溢出的示例 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 版本应使用链接，JSON 响应应使用 JSON 架构属性。<a>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 架构告诉我们 XML 中的问题是什么样子的。可以为JSON提供JSON-SCHEMA，并在HTML中为新问题提供表单。

假设用户想要 GET 问题：

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应用程序的成本相同。这就是为什么像这样的工具如此之少，而且通常它们并不那么好。