在PHP中自動記錄REST API

Question

phpDocumentor似乎是記錄PHP代碼的標準，但我不得不想知道爲什麼它沒有在幾年內更新..？

但是，它似乎不適合記錄REST API的入口點; IE，系統的最終用戶可能會感興趣的外部可訪問入口點，而不是記錄所有內部類和類似的東西 - 這些只是api開發人員感興趣的東西。

我正在尋找一些我可以說的東西，嘿這裏的方法可以通過REST在這個URL上進行外部訪問，這裏是GET或POST參數，它支持GET/POST/etc HTTP方法，它返回JSON或XML或其他。

此信息將能夠生成一個API文檔。它也可以由代碼內部使用自動過濾輸入，驗證輸出，創造基本單元測試，等等

Answer 1

到最容易的事情是使用的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

最後，有一個框架在那裏（我知道的，我敢肯定有萬噸），使用說明做寧靜善良的種種（也許是拯救自己的一些工作）：http://www.recessframework.org/

。希望幫助！

Answer 2

揚鞭似乎很有前途，但它需要你的API暴露自身以兼容的方式......這是相當不錯的，但是，有一個測試臺等所有內置...你可以下載一個JavaScript版本和運行它在你的服務器旁邊的PHP API。

編輯：這裏是鏈接，它不是那麼容易找到，在谷歌，如果你沒有全名... ...笑揚鞭的UI：https://github.com/wordnik/swagger-ui

Answer 3

一個RESTful API應該完全發現和自動記錄。你只需要一個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-架構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和發佈一個新問題。它還告訴我們如何通過提供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="https://stackoverflow.com/questions/intersting" title="Intersting Questions"/> 
    <link href="https://stackoverflow.com/questions/hot" title="Hot Questions"/> 
</questions> 

現在，一切都再掛。事情繼續以服務描述自己的方式繼續下去。 Netflix API遵循類似的原則，但缺少一些自動發現功能。

This Brazillian Government API描述了自己使用RDF。這是我見過的最好的RESTful樣本之一。嘗試將.rdf更改爲.xml，.json或.html。 （全都用葡萄牙語，對不起）。

PHP中RESTful API的最佳工具是Respect\Rest。它具有我在這裏描述的大部分工作流程已經引導，新功能即將到來（它仍然在0.4x版本）。

爲RESTful應用程序構建文檔系統的成本與構建RESTful應用程序相同。這就是爲什麼有那麼少的工具，通常他們不太好。

Answer 4

我知道的3個PHP集成與招搖：

• Swagger PHP composer

• Swagger PHP Symfony bundle

• Restler 3.0

所有這些都應有助於自動創建一個招搖-SP ec，它可以讓你從swagger-ui訪問。然後你就可以生成API客戶端等

Answer 5

我發現一個名爲apidoc，做在DOC-ING RESTfuls一個真棒的工作很節點包。它允許大量的特定於API的標籤用params和類似的東西來做，但真正賣給我的是它爲每種方法生成的，在文檔中的測試表單。

我用它在我的DEVOPS骨架項目在https://github.com/ardkevin84/devops.skel.php-with-docs-metrics，但你可以在https://github.com/ardkevin84/api.callloop看到我callloop API項目實際輸出。該apidoc指數是建立/ API的文檔/ apidoc/index.html的

唯一的缺點，如果它是一個，就是它 - 自然 - 需要自己的文檔塊。不過，它不會與'本地'Docblock衝突。 apidoc塊不需要在方法之前，所以我通常將它們組合在我的端點文件的頂部，其他文檔引擎不會將它們與類文檔相關聯。

一個副產品：該作品偉大與外牆;我在端點中使用了門面和工廠，並且apidoc分析器允許我分別處理外觀條件。在下面的示例中，「訂閱」，「取消訂閱」和「觸發器」由單個入口點處理，但它們分開記錄。

示例：此文檔塊

/** * @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與查詢參數：這是一個從節點安裝包不支持enpoints像service.php?param=value，但有在https://github.com/apidoc/apidoc/pull/189在git倉庫拉請求，其中涉及這一點。這是對默認模板的基本修復。我將幾行代碼修補到了我的節點包中，它就像一個魅力一樣。

無恥自我推銷：這可能在自動構建下使用起來要容易得多。看看我的DEVOPS項目上面一個kickstart;）這是一個從詹金斯的PHP分叉，但在幾個文檔引擎和存根目標的東西增加了像推生成的文檔\指標到本地主機的路徑和包裝輸出版本（拉鍊，焦油等）