web-dev-qa-db-ja.com

自動ドキュメント化REST API in PHP

phpDocumentorはドキュメント化の標準であるようですPHP=コードですが、何年も更新されていないのはなぜでしょうか？

ただし、REST API; IEのエントリポイントを文書化するのには適していないと思われます。IEは、システムのエンドユーザーが関心を持つ、外部からアクセス可能なエントリポイントであり、内部クラスなど-APIの開発者のみが関心を持つもの。

私は私が言うことができる何かを探しています、ここでちょっとこのメソッドはRESTこのURLからアクセスできます、GETまたはPOST引数を取ると、 GET/POST/etc HTTPメソッドをサポートし、JSONまたはXMLなどを返します。

この情報により、APIドキュメントを生成できます。また、コードを内部的に使用して、入力の自動フィルタリング、出力の検証、基本的な単体テストの作成などを行うこともできます。

phprestdocumentation-generation
23
Greywire

私は3 PHP swaggerとの統合を知っています：

すべてがswagger-specの自動作成に役立ち、swagger-uiからアクセスできるようになります。次に、APIクライアントなどを生成できます。

19
fehguy

RESTfulsのドキュメント化で素晴らしい仕事をする apidoc という名前の素晴らしいノードパッケージを見つけました。これにより、大量のAPI固有のタグでパラメーターなどを処理できますが、実際に販売されたのは、メソッドごとに生成されたドキュメント内のテストフォームです。

https://github.com/ardkevin84/devops.skel.php-with-docs-metrics の私のdevopsスケルトンプロジェクトで使用していますが、actual https://github.com/ardkevin84/api.callloop にある私のcallloop apiプロジェクトの出力。 apidocインデックスはbuild/api-docs/apidoc/index.htmlです。

唯一の欠点は、それが1つの場合、それは（当然のことながら）独自のdocblockを取ることです。ただし、「ネイティブ」Docblockと競合しません。 apidocブロックはメソッドの前に置く必要はないので、通常は、他のドキュメントエンジンがクラスドキュメントに関連付けないエンドポイントファイルの先頭にまとめます。

副産物：これはファサードで素晴らしい機能します。私はエンドポイントでファサードとファクトリーを頻繁に使用しており、apidocパーサーでファサード条件を個別に処理できます。以下の例では、「subscribe」、「unsubscribe」、および「trigger」は単一のエントリポイントによって処理されますが、それらは別々に文書化されています。

例：このdocblock

/**
 * @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
 */

この出力を生成するために必要であり、テストフォーム DOCBLOCK output

重要、クエリパラメータで標準の$ _GETを使用している場合：ノードからインストールされたパッケージはservice.php?param=valueのようなエンドポイントをサポートしていませんが、プルリクエストがgit repo at https://github.com/apidoc/apidoc/pull/189 これはこれに対処します。これは、デフォルトのテンプレートに対する基本的な修正です。ノードパッケージに数行をパッチしましたが、それは魅力のように機能します。

恥知らずな自己宣伝：これはおそらく、自動化されたビルドで使用する方がはるかに簡単です。上記の私のdevopsプロジェクトでキックスタートを確認してください;）これはjenkins-phpからフォークされますが、生成されたdocs\metricsをローカルホストパスにプッシュしたり、リリースのパッケージ化出力（Zip、tarなど）のために、いくつかのドキュメントエンジンとスタブターゲットを追加します）

10
Kevin Ard

RESTful APIは完全に検出可能で、自動ドキュメント化されている必要があります。あなたはURLだけを必要とし、それにリンクされている他のすべてはそれ自身を説明するべきです。ユートピアのように聞こえますが、それは可能です。

たとえば、stackoverflowのようなサンプルURLから始めましょう： http://restfuloverflow.com （例）

RESTfulリソースで最初に行うことは、OPTIONSリクエストです。サーバーに最も適切なMIMEタイプに応答するように指示するには、常にAcceptヘッダーを含める必要があります。

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-Schema 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とPOST新しい質問が可能であることを教えてくれました。また、XMLスキーマを提供することにより、XMLの質問がどのように見えるかを教えてくれました。JSON-SCHEMAを提供することができますJSONの場合、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="/questions/intersting" title="Intersting Questions"/>
    <link href="/questions/hot" title="Hot Questions"/>
</questions>

今、すべてが再びリンクされています。事はサービスがそれ自体を記述する方法で進み続けます。 Netflix API は同様の原則に従いますが、一部の自動検出機能がありません。

このブラジル政府のAPI は、RDFを使用して自分自身を説明します。これは、私が今まで見た中で最高のRESTfulサンプルの1つです。 .rdfを.xml、.json、または.htmlに変更してみてください。 （すべてポルトガル語です。申し訳ありません）。

PHPは Respect\Rest のRESTful APIに最適なツールです。ここで説明したワークフローのほとんどはすでにブートストラップされており、新しい機能が追加されます（まだ0.4xバージョン）。

RESTfulアプリケーションの文書化システムを構築するコストは、RESTfulアプリケーションの構築と同じです。これがそのようなツールが非常に少ない理由であり、通常それらはそれほど良くありません。

9
alganet

Swaggerは有望に思われますが、APIが互換性のある方法でそれ自体を公開する必要があります...しかし、それは非常に素晴らしいですが、テストコンソールなどがすべて組み込まれています... JavaScriptバージョンをダウンロードしてサーバーで実行できますPHP APIと一緒に。

編集：ここにリンクがあります、あなたがフルネームを持っていない場合、それはグーグルで見つけるのはそれほど簡単ではありません...笑... Swagger-UI： https://github.com/wordnik/swagger-ui

1
RVN

最も簡単な方法は、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

最後に、注釈を使用してあらゆる種類の安らぎを（おそらくはある程度の作業を節約して）実行するフレームワークが1つあります（私は知っていますが、確かにたくさんあります）。 https：// github。 com/recess/recess

お役に立てば幸いです。

0
Ian Selby