Laravel API Documentation Generatorがインストールできないのでscribeをいれてみた

# 概要
https://github.com/mpociot/laravel-apidoc-generator

既存のLaravelプロジェクトへSwaggerを導入するにあたり、「Laravel API Documentation Generator」なる便利パッケージでSwaggerのyamlを自動生成できることを知りました。

しかし、インストールを試みたところ↓のエラーが発生しインストールできませんでした。

```
Your requirements could not be resolved to an installable set of packages.

  Problem 1
    - mpociot/laravel-apidoc-generator v4.x-dev requires ramsey/uuid ^3.8 -> found ramsey/uuid[3.8.0, ..., 3.x-dev] but the package is fixed to 4.2.1 (lock file version) by a partial update and that version does not match. Make sure you list it as an argument for the update command.
    - mpociot/laravel-apidoc-generator[4.8.0, ..., 4.8.2] require illuminate/console ^5.7|^6.0|^7.0 -> found illuminate/console[v5.7.0, ..., 5.8.x-dev, v6.0.0, ..., 6.x-dev, v7.0.0, ..., 7.x-dev] but these were not loaded, likely because it conflicts with another require.
    - Root composer.json requires mpociot/laravel-apidoc-generator ^4.8 -> satisfiable by mpociot/laravel-apidoc-generator[4.8.0, 4.8.1, 4.8.2, v4.x-dev].

Use the option --with-all-dependencies (-W) to allow upgrades, downgrades and removals for packages currently locked to specific versions.

Installation failed, reverting ./composer.json and ./composer.lock to their original content.
```

**「Laravel API Documentation Generator」をインストールするには、「ramsey/uuid」というパッケージのバージョンが3.8系でないとダメだよ。なのにインストールされているのは4.2.1だよ。**

という感じ。

よくあるパッケージの依存関係エラーが発生しました。
結局依存関係は解消せず、別のパッケージをインストールすることで回避したのですが、そこに至るまでの判断や調べたことなどをまとめます。

# 原因

https://github.com/mpociot/laravel-apidoc-generator/issues/796

たくさんの方がissueとして挙げられているようで、Laravel8系でインストールしようとすると発生するようです。

# 解決策・・・？
> Here's a temporary solution to continue using this package. 😁
  ```
  "mpociot/documentarian": "dev-master as 0.4.0",
  "mpociot/laravel-apidoc-generator": "dev-master",
```

issueの中に「これなら"一時的に"動くよ」というコメントがあったのですが、**dev-master**という記載を初めてみたので、調べてみました。

# dev-masterとは？ 使うべきではなさそう？

https://azix.hatenablog.com/entry/2019/01/24/Composer%E3%81%A7dev-master%E3%82%92%E6%8C%87%E5%AE%9A%E3%81%97%E3%81%A6%E3%81%84%E3%82%8Bpackage%E3%81%AE%E6%AD%A3%E7%A2%BA%E3%81%AA%E3%83%90%E3%83%BC%E3%82%B8%E3%83%A7%E3%83%B3%E3%81%AE%E7%A2%BA%E8%AA%8D

> このバージョンを指定するとmasterの最新コミットが適用される．

https://stackoverflow.com/questions/19009334/when-dev-master-should-be-used-in-composer-json

> While composer.lock does lock the dependency to a specific commit even when using dev-master ... every composer update will update the dependency to the latest version and afterwards update the lockfile.

composerをupdateするたびに最新バージョンがインストールされるとのことで、依存関係もその度に更新されてしまうようです。
知らないうちに依存関係のエラーが発生するなど**後々の負債となってしまうのは明らか**なので、この方法は見送ることにしました。

# 結局諦めることに
https://github.com/knuckleswtf/scribe

結局「Laravel API Documentation Generator」の使用は諦め、issueの中でおすすめされていたこちらを使用することにしました。

# しかしこちらもインストールできない・・・

```
composer require --dev knuckleswtf/scribe:4.9.0

Info from https://repo.packagist.org: #StandWithUkraine
./composer.json has been updated
Running composer update knuckleswtf/scribe
Loading composer repositories with package information
Info from https://repo.packagist.org: #StandWithUkraine
Updating dependencies
Your requirements could not be resolved to an installable set of packages.

  Problem 1
    - Root composer.json requires knuckleswtf/scribe 4.9.0 -> satisfiable by knuckleswtf/scribe[4.9.0].
    - knuckleswtf/scribe 4.9.0 requires nunomaduro/collision ^5.10|^6.0 -> found nunomaduro/collision[v5.10.0, v5.11.0, v5.x-dev, v6.0.0, ..., v6.x-dev] but the package is fixed to v5.9.0 (lock file version) by a partial update and that version does not match. Make sure you list it as an argument for the update command.

Use the option --with-all-dependencies (-W) to allow upgrades, downgrades and removals for packages currently locked to specific versions.

Installation failed, reverting ./composer.json and ./composer.lock to their original content.
```
依存関係のエラーが発生し、解消したらまたエラーの繰り返し・・・。

しょうがないのでcomposer updateしてから再度インストールすることに。
無事インストールされ、yamlの生成など問題なくできているので、「Laravel API Documentation Generator」がインストールできない場合はこちらの使用をお勧めします。

https://scribe.knuckles.wtf/laravel/

# じゃあ「Laravel API Documentation Generator」でいいのでは？
結局composer updateする羽目になったので、「Laravel API Documentation Generator」のインストールを再度試してみたところ、問題なくインストールされました。
しかし、
```
php artisan vendor:publish --provider="Mpociot\ApiDoc\ApiDocGeneratorServiceProvider" --tag=apidoc-config
```
を実行してもapidoc.phpがconfig以下に来ません。
```
No publishable resources for tag [apidoc-config].
```
scribeが使えているので、もういいかと思い諦めました。
Laravel8系を使用している場合はscribeを最初から使用する、で問題ないと思います。

# composer updateの影響
本来ならcomposer updateによってパッケージのバージョンが上がるため、本番環境等への影響を検証する必要があります。
ですが今回は、
- Swagger用のyaml生成だけをこのブランチで実施
- パッケージのインストールはDevelopブランチ等へはマージしない
- 生成されたyamlだけマージする

という形でよいと判断しました。

今後APIの改修が発生した場合にはyamlをエディタで編集する形とすれば、特に問題ないかなと思いました。
(yaml生成のためのアノテーションでコードが汚れることもないし・・・)

ただ、今後他にもパッケージのインストールが必要となるときがあると思うので、その時はアップデートの検証が必要になると思います。

# 参考
https://access-jp.co.jp/blogs/development/256

http://blog.a-way-out.net/blog/2015/06/19/composer-version-tilde-and-caret/