swagger-php で複数行の説明を書く

Swagger PHP で API の説明を書く際、わかりやすく書こうとするとどうしても長くなり改行を入れたくなります。ただ、改行を入れると Doc コメントの見た目が崩れるので、きれいな書き方を探してみました。

PHP のコメントに markdown 形式で書くので、 .editorconfig は以下を追加しておきます。改行で文末にスペース２つ入れた時に消えてしまうので。

[*.php]
trim_trailing_whitespace = false

深く考えずに複数行説明を書くと以下のようになります。

    /**
     * swagger-php で 複数行の説明を書く例（失敗ケース）
     *
     * @OA\Get(
     *     path="/multiline-description/case-1",
     *     description="１行目  
     *     ２行目  
     *     ３行目",
     *     @OA\Response(response="200", description="")
     * ),
     */
    public function case1(Request $request)
    {
        return [];
    }

これを Swagger UI で表示してみると・・・

アスタリスクを拾ってそのまま出てしまいます。ならばアスタリスクを消せばいいのではという事で、以下の書き方が紹介されていました。

    /**
     * swagger-php で 複数行の説明を書く例（成功例１）
     *
     * @OA\Get(
     *     path="/multiline-description/case-2",
     *     description="
１行目  
２行目

* ３行目",
     *     @OA\Response(response="200", description="")
     * ),
     */
    public function case2(Request $request)
    {
        return [];
    }

と書くと

（Swagger UI では）きれいに表示されました。ただ、コメントの見た目が美しくないですね・・・。ちなみに空行以降はインデントを入れるとコードブロックになってしまうので、左につめて書く必要があります。

ところで、 swagger-php をインストールする際、 doctrine/annotations というパッケージがインストールされます。アノテーションの解析には Doctrine と同じものを使用しているようです。

そういえば、 Doctrine のアノテーションって定数使えたような、ということで

    const DESCRIPTION = <<<DOC
１行目  

* ２行目
* ３行目
DOC;
    /**
     * swagger-php で 複数行の説明を書く例（成功例２）
     *
     * @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 コメントが長くなるのは好きではない（そもそもアノテーション自体そんなに・・・）ので、別の場所に書けるというのもおすすめする理由の１つです。

動作確認に使ったコードはここにあります。