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/
swagger
2.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のエンドポイントやパラメータなどを、バラバラに管理しなくても済むようにしたいなと。
ではでは。
Author And Source
この問題について(NelmioApiDocBundleの@ApiDocはそのうちオワコンになるから、今のうちアップグレードしておいてSwagger-phpアノテーションに書き換える), 我々は、より多くの情報をここで見つけました https://qiita.com/imunew/items/bdea1e577f066054355f著者帰属:元の著者の情報は、元のURLに含まれています。著作権は原作者に属する。
Content is automatically searched and collected through network algorithms . If there is a violation . Please contact us . We will adjust (correct author information ,or delete content ) as soon as possible .