2

OK、php コードからドキュメントを生成するための PhpDocumentor があることは知っています。長い間更新されていないようです (しかし、彼らはほとんどの機能が完成していると考えているかもしれません)。

これは、他のプログラマーのために文書化するのには適しているかもしれませんが、Web サービスの外部「API」を文書化するのにはあまり適していないようです。IE で MVC 構造化プロジェクトを作成した場合、PhpDocumentor はそのプロジェクトの他の開発者向けにすべてのモデルと内部ライブラリなどを文書化するのに最適ですが、それが提供する Web サービスを文書化するにはどうすればよいですか?

次のようなタグを使用して、コントローラーのメソッドを文書化できる場所を考えています。

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

生成されたドキュメントでは、POST 要求を実行する必要があることが示されます。JSON データが返され、それにアクセスするための URL はhttp://whatever.com/device/addです。明らかに、これらのサービス呼び出しのベース URL を定義するドキュメント用のグローバル構成ファイルがあります。

この時点で、phpdoc ブロックでリフレクションを使用して (または追加ライブラリで注釈を使用して) 自分で何かを実装し、アプリケーションで直接ドキュメントに動的にアクセスできるようにしようと考えています。

4

2 に答える 2

1

PhpDocumentor よりも DoxyGen (または PHPxRef) を好むかもしれません。

「これは、他のプログラマーのために文書化するのには適しているかもしれませんが、Web サービスの外部 "API" を文書化するのにはあまり適していないようです」.

外部から見える API 関数だけにDoxyGen (または何でも) のコメントを入れてみませんか?

それぞれについて説明し、@param [in]、 、@param [out]およびを使用し@returnます。

それはあなたが望むものを達成しませんか？それとも私は何かを逃しましたか？

于 2010-01-22T02:36:50.820 に答える
0

あなたの質問（APIの文書化（特にRESTfulの場合））は、WADLを使用することだと思います。ソースから生成されることはありませんが（PHPにはそのためのツールはありません）、WADLはサービスの文書化に最適です。

あらゆる種類のメディアタイプ、すべての応答コード、およびそれらの処理方法でサンプルペイロードを使用できます。実際に必要なものはすべてあります。

于 2010-01-22T02:06:47.520 に答える