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


## どういうことか
[NelmioApiDocBundle](https://github.com/nelmio/NelmioApiDocBundle)のgithubリポジトリを見ると、`SWAGGERUI`というブランチができています。
そのブランチに切り替えると、気付きにくいですが、ひっそりと[UPGRADING-3.0.md](https://github.com/nelmio/NelmioApiDocBundle/blob/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`をアップグレード

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

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

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

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

- `assets:install`

  ```bash
$ 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`に変更する

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

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

  ```bash
$ app/console cache:clear
```

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

```bash
$ 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/`にアクセスすると、下記のようにページが表示されるはずです。

![NelmioApiDocBundle_v3.png](https://qiita-image-store.s3.amazonaws.com/0/26422/5acbe2a3-d923-2c9a-7230-954c40befa0c.png "NelmioApiDocBundle_v3.png")

### Swagger形式でjsonファイルを出力
v2まであった`api:swagger:dump`コマンドは削除され、かわりに、`swagger`コマンドが使えるようになっています。

```bash
$ bin/swagger src/
```

`swagger`2.0 形式のJSONファイルが下記のように出力されます。


```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`の仕様については、[こちら](http://swagger.io/specification/)を参照ください。

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

ではでは。