NelmioApiDocBundleの@ApiDocはそのうちオワコンになるから、今のうちアップグレードしておいてSwagger-phpアノテーションに書き換える

どういうことか

NelmioApiDocBundleのgithubリポジトリを見ると、SWAGGERUIというブランチができています。
そのブランチに切り替えると、気付きにくいですが、ひっそりとUPGRADING-3.0.mdが置かれていて、下記のようなことが書かれています。

@ApiDocアノテーションは削除されるので、これからはSwagger-php形式のアノテーションを使用する

多少、意訳は入っているものの、どうやら@ApiDocアノテーションは本当に削除されるようです。

NelmioApiDocBundle has been entirely refactored in 3.0 to focus on Swagger and most of it has changed.

実際、試してみた

アップグレード

• composerでNelmioApiDocBundleをアップグレード

$ composer require "nelmio/api-doc-bundle:dev-SWAGGERUI"

• stability云々でエラーになる場合は、"minimum-stability": "dev"をcomposer.jsonに追加

• @ApiDocおよびNelmio\ApiDocBundle\Annotation\ApiDocは削除されているので、使用箇所はいったん全部削除する

アップグレード後にやること

• assets:install

$ app/console asset:install --symlink

 Trying to install assets as absolute symbolic links.

 --- -------------------- ------------------ 
      Bundle               Method / Error    
 --- -------------------- ------------------ 
  ✔   FrameworkBundle      absolute symlink  
  ✔   NelmioApiDocBundle   absolute symlink  
 --- -------------------- ------------------ 


 [OK] All assets were successfully installed. 

• ルーティング用のファイルを変更 下記のように、@NelmioApiDocBundle/Resources/config/routing.ymlは削除されているので、代わりに@NelmioApiDocBundle/Resources/config/routing/swaggerui.xmlに変更する

## app/config/routing_dev.yml
NelmioApiDocBundle:
        resource: "@NelmioApiDocBundle/Resources/config/routing/swaggerui.xml"
        prefix:   /doc

• 設定ファイル変更したので、cache:clear

$ app/console cache:clear

APIドキュメントページにアクセス

$ app/console server:start


 [OK] Web server listening on http://127.0.0.1:8000

ビルトインサーバーを起動した後、http://127.0.0.1:8000/app_dev.php/doc/にアクセスすると、下記のようにページが表示されるはずです。

Swagger形式でjsonファイルを出力

v2まであったapi:swagger:dumpコマンドは削除され、かわりに、swaggerコマンドが使えるようになっています。

$ bin/swagger src/

swagger2.0 形式のJSONファイルが下記のように出力されます。

# /path/to/app/swagger.json
{
    "swagger": "2.0",
    "paths": {
        "/example/{memberId}": {
            "get": {
                "parameters": [
                    {
                        "name": "memberId",
                        "in": "path",
                        "required": true,
                        "type": "integer"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK"
                    }
                }
            }
        }
    },
    "definitions": {}
}

Swaggerの仕様については、こちらを参照ください。

おわりに

個人的にSwaggerに期待するのは、人間のためのドキュメント生成ではなく、ソフトウェアが再利用するためのスペックです。
APIクライアントコードの自動生成など、WebAPIのエンドポイントやパラメータなどを、バラバラに管理しなくても済むようにしたいなと。

ではでは。