Swagger PHP で API の説明を書く際、わかりやすく書こうとするとどうしても長くなり改行を入れたくなります。ただ、改行を入れると Doc コメントの見た目が崩れるので、きれいな書き方を探してみました。
PHP のコメントに markdown 形式で書くので、 .editorconfig
は以下を追加しておきます。改行で文末にスペース2つ入れた時に消えてしまうので。
[*.php] trim_trailing_whitespace = false
深く考えずに複数行説明を書くと以下のようになります。
/** * swagger-php で 複数行の説明を書く例(失敗ケース) * * @OA\Get( * path="/multiline-description/case-1", * description="1行目 * 2行目 * 3行目", * @OA\Response(response="200", description="") * ), */ public function case1(Request $request) { return []; }
これを Swagger UI で表示してみると・・・

アスタリスクを拾ってそのまま出てしまいます。ならばアスタリスクを消せばいいのではという事で、以下の書き方が紹介されていました。
/** * swagger-php で 複数行の説明を書く例(成功例1) * * @OA\Get( * path="/multiline-description/case-2", * description=" 1行目 2行目 * 3行目", * @OA\Response(response="200", description="") * ), */ public function case2(Request $request) { return []; }
と書くと

(Swagger UI では)きれいに表示されました。ただ、コメントの見た目が美しくないですね・・・。ちなみに空行以降はインデントを入れるとコードブロックになってしまうので、左につめて書く必要があります。
ところで、 swagger-php をインストールする際、 doctrine/annotations というパッケージがインストールされます。アノテーションの解析には Doctrine と同じものを使用しているようです。
そういえば、 Doctrine のアノテーションって定数使えたような、ということで
const DESCRIPTION = <<<DOC 1行目 * 2行目 * 3行目 DOC; /** * swagger-php で 複数行の説明を書く例(成功例2) * * @OA\Get( * path="/multiline-description/case-3", * description=\App\Http\Controllers\v1\MultilineDescription::DESCRIPTION, * @OA\Response(response="200", description="") * ), */ public function case3(Request $request) { return []; }
と書いてみると

こちらも表示されました。
self:: とか、 クラス名だけ MultilineDescriptionController::DESCRIPTION
でも試してみましたが動かないので、 namespace は必須のようです。最初の \ も必要なので書き忘れないようにしましょう。
個人的には定数使った方が見やすいと思います。あまり Doc コメントが長くなるのは好きではない(そもそもアノテーション自体そんなに・・・)ので、別の場所に書けるというのもおすすめする理由の1つです。
動作確認に使ったコードはここにあります。