在 PHP 中自动记录 REST API

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


推荐