來自PHP代碼的自動文檔

好的，我知道有PhpDocumentor從PHP代碼生成文檔。看起來它很久沒有更新（但也許他們的主要功能已完成）。來自PHP代碼的自動文檔

雖然這可能對記錄其他程序員的事情很好，但它似乎不適合記錄Web服務的外部「API」。 IE瀏覽器，如果我有一個很好的MVC結構化項目，PhpDocumentor可能非常適合記錄所有模型和內部庫以及該項目的其他開發人員，但是如何記錄它提供的Web服務？

我在想什麼，你可以記錄使用的標籤，如控制器的方法：

/** 
@service /device/add 
@access POST 
@return JSON 
*/

這在生成的文檔會顯示你需要做一個POST請求時，它會返回JSON數據和訪問它的URL是http://whatever.com/device/add。很明顯，文檔中會有一個全局配置文件，它定義了這些服務調用的基礎url。

在這一點上，我想我只是在phpdoc塊中使用反射來實現自己的東西（或者在附錄庫中使用註釋），並在應用程序中動態訪問文檔。

來源

2010-01-22 Greywire

幾小時前我問了幾乎相同的問題:) http://stackoverflow.com/questions/2121710/is-there-a-standard-for-documenting-get-post-parameters – 2010-01-23 03:00:13

我想你的問題（記錄一個API（特別是如果它的RESTful））將使用WADL。授予它不會從源生成（在PHP中沒有工具），但WADL非常適合記錄服務。

您可以在各種媒體類型，所有響應代碼以及您如何處理它們的過程中擁有樣本有效載荷 - 您真正需要的一切。

來源

2010-01-22 02:06:47

WADL的東西很有趣。我會更多地考慮這一點。我希望看到WADL在PHP中使用DocBlock註釋的一些事情，以及一個從這些（也可能是WADL文件）生成文檔的解析器。 – Greywire 2010-01-23 02:56:24

我不確定WADL是否正確。 WADL似乎更多地是以可用於生成代碼的方式定義Web服務，而不是其他方式（可以生成文檔的註釋的代碼）。我認爲真正酷的是某種完全通用的生成器，它可以讓你定義你想要的任何標籤併爲這些標籤提供處理程序。這樣可以很好地發揮Annotations這樣的概念，你可以在這裏構建自己的標籤類型（即註釋對代碼和文檔生成器意味着什麼） – Greywire 2010-01-23 19:43:19

您可能更喜歡DoxyGen（或PHPxRef）到PhpDocumentor。

「雖然這可能對記錄其他程序員的事情很好，但它似乎不適合記錄Web服務的外部」API「」。

爲什麼不把DoxyGen（或其他）的評論只有納入外部可見的API函數？

給每個的描述，並使用@param [in]，@param [out]和@return。

難道你沒有達到你想要的？或者我錯過了什麼？

來源

2010-01-22 02:36:50 Mawg

因爲我也想記錄其他程序員的內部東西（更何況我自己）... – Greywire 2010-01-23 19:16:11

是的，我明白這一點。但是，如果您僅爲交互操作添加註釋*，然後運行DoxyGen，那麼您已生成了可供其他人使用的界面文檔。會不會工作？ – Mawg 2010-01-24 02:58:16

我不確定你的意思只是爲接口提供意見嗎？如果您的意思是，將控制器方法記錄爲外部服務調用，並將模型記錄爲內部模型，這些方法在我的設計中不起作用，因爲在任何模型中都有用於標準CRUD操作的通用控制器，所以文檔的唯一位置是模型方法（我也使用註釋來定義模型的數據庫訪問等）。 – Greywire 2010-01-25 21:11:23

來自PHP代碼的自動文檔

回答

相關問題