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


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つです。

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


コメントを残す

メールアドレスが公開されることはありません。 が付いている欄は必須項目です

このサイトはスパムを低減するために Akismet を使っています。コメントデータの処理方法の詳細はこちらをご覧ください