2

Swagger-php を使用して、Swagger を使用して PHP Rest API のドキュメントを生成しようとしています。

ドキュメンテーションのために巨大なコメントブロックを持つのが好きかどうかはよくわかりませんが、それは問題ではありません。

私には2つの道があります：

/user/ [POST]
/user/login [POST]

両方とも、私の PHP コードで同じメソッド login() を呼び出します。

/user/ [POST] は単なる /user/login [POST] のエイリアスだと言う方法はありますか?

両方とも操作のリストに表示され、ドキュメントが完成し、ユーザーにオプションを提供するためのパスが異なるだけで、同じことを行うと述べてください。

もちろん、コメント ブロックをコピーして貼り付けることもできますが、別のメソッドを呼び出すだけの 1 行のメソッドに 50 行のコメント ブロックは必要ありません。

何か案は ？

4

2 に答える 2

4

参照を使用することは、swagger-php で@SWG\Path.

/**
 * @SWG\Post(
 *   path="/user/login",
 *   @SWG\Response(response=200, description="OK")
 * )
 * @SWG\Path(path="/user/", ref="#/paths/user~1login");
 */
function login() {
  ...
}

ただし、swagger は API を文書化するためのものであることを忘れないでください。/user/login がログイン用の正規の API エンドポイントである場合、swagger ドキュメントでエイリアスを公開することさえしません。

@Markでは、パスはまだ操作を所有していますが、いくつかのトリックを使用して自動的に作成し@SWG\Pathます。一般的なユースケースはphpメソッドごとに1つのhttp-methodを文書化することであるため、これはボイラープレートを回避しますが、メソッドが複数のhttp-を処理する場合@SWG\Path直接使用する方が短い場合があるメソッド:

/**
 * @SWG\Path(
 *   path="/example",
 *   @SWG\Get(response=200, description="OK"),
 *   @SWG\Post(response=200, description="OK"),
 *   @SWG\Put(response=200, description="OK")
 * )
 */
 function thisMethodHandlesGetPostAndPutRequests() {
 }
于 2016-03-19T16:40:12.507 に答える