laravel8自作メモAPIをswaggerで、コードから自動ドキュメント化してみた。思ってた自動化と違う！

参考URL
https://blog.asial.co.jp/2025

なんか自動的にソース解析してドキュメント化してくれるかと思ったら、ソースに自分でアノテーション(コメント)を書け！って事？
web.phpのresource()くらいのを期待してたのに～。
文句を言っていてもしょうがない、とりあえず一回やってみよう。

1, swaggerのパッケージをインストール

composer require "darkaonline/l5-swagger"

1	composer require "darkaonline/l5-swagger"

2, app/Http/Controllers/MemoController.phpにアノテーションを書く

/**
 * @OA\Info(
 *     version="1.0.0",
 *     title="L5-Swaggerサンプル",
 *     description="サンプル",
 * )
 */
class MemoController extends Controller
{
    /**
     * @OA\Get(
     *     path="/hello",
     *     operationId="hello",
     *     tags={"タグ"},
     *     summary="ハロー",
     *     description="こんにちは",
     *     @OA\Response(
     *         response=200,
     *         description="成功",
     *         @OA\JsonContent(
     *             type="object",
     *             @OA\Property(
     *                 property="message",
     *                 type="string",
     *                 description="メッセージ",
     *                 example="Hello"
     *             )
     *         )
     *     )
     * )
     */
    // 全レコード表示
    public function index()
    {

/**

* @OA\Info(

* version="1.0.0",

* title="L5-Swaggerサンプル",

* description="サンプル",

* )

class MemoController extends Controller

{

/**

* @OA\Get(

* path="/hello",

* operationId="hello",

* tags={"タグ"},

* summary="ハロー",

* description="こんにちは",

* @OA\Response(

* response=200,

* description="成功",

* @OA\JsonContent(

* type="object",

* @OA\Property(

* property="message",

* type="string",

* description="メッセージ",

* example="Hello"

* )

// 全レコード表示

public function index()

{

3, APIドキュメント生成

php artisan l5-swagger:generate
Regenerating docs default

1 2	php artisan l5-swagger:generate Regenerating docs default

.envファイルに、以下の記述をしておけばブラウザでアクセスする毎に自動生成してくれるらしい。
こういうのは、忘れないように先頭に記述するのが良いのだろうか・・・？
L5_SWAGGER_GENERATE_ALWAYS=true

4,ブラウザでアクセス
http://localhost/restful/public/api/documentation

まあ、一度作ってしまえば、RestfulAPIの使いまわしは出来るか？

いやいや、自動化の方法はあるはず！と探してたらあった
https://qiita.com/morimorim/items/e0a2c8e2011208d50278

でも、エラーになる…。

composer require mpociot/laravel-apidoc-generator
Using version ^4.8 for mpociot/laravel-apidoc-generator
./composer.json has been updated
Running composer update mpociot/laravel-apidoc-generator
Loading composer repositories with package information
Updating dependencies
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.1.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.

composer require mpociot/laravel-apidoc-generator

Using version ^4.8 for mpociot/laravel-apidoc-generator

./composer.json has been updated

Running composer update mpociot/laravel-apidoc-generator

Loading composer repositories with package information

Updating dependencies

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.1.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.

英語のQ&Aサイトを見てみると
https://github.com/mpociot/laravel-apidoc-generator/issues/796

composer.jsonのfakerphp/faker を削除して
“mpociot/documentarian”: “dev-master as 0.4.0”,
“mpociot/laravel-apidoc-generator”: “dev-master”,
を追記して、composer updateしたら大丈夫だった。って書いてあったけど
mpociot/laravel-apidoc-generator
のphpソースがphp8で予約語になったmatchを使っていてコケる～。
しょうがない、php7.4で最初からやり直そう。

# インストール
composer require mpociot/laravel-apidoc-generator
# ドキュメント生成
php artisan apidoc:generate
Processed route: [GET] api/documentation
Processed route: [GET] docs/{jsonFile?}
Processed route: [GET] docs/asset/{asset}
Processed route: [GET] api/oauth2-callback
Processed route: [GET] api/memo
Processed route: [GET] api/memo/create
Processed route: [POST] api/memo
Processed route: [GET] api/memo/{memo}
Processed route: [GET] api/memo/{memo}/edit
Processed route: [PUT,PATCH] api/memo/{memo}
Processed route: [DELETE] api/memo/{memo}
Skipping route: [GET] api/user: Closure routes are not supported.
Skipping route: [GET] /: Closure routes are not supported.
Writing index.md and source files to: resources/docs
Wrote index.md and source files to: resources/docs
Generating API HTML code
Wrote HTML documentation to: public/docs
Generating Postman collection
Wrote Postman collection to: public/docs/collection.json

# インストール

composer require mpociot/laravel-apidoc-generator

# ドキュメント生成

php artisan apidoc:generate

Processed route: [GET] api/documentation

Processed route: [GET] docs/{jsonFile?}

Processed route: [GET] docs/asset/{asset}

Processed route: [GET] api/oauth2-callback

Processed route: [GET] api/memo

Processed route: [GET] api/memo/create

Processed route: [POST] api/memo

Processed route: [GET] api/memo/{memo}

Processed route: [GET] api/memo/{memo}/edit

Processed route: [PUT,PATCH] api/memo/{memo}

Processed route: [DELETE] api/memo/{memo}

Skipping route: [GET] api/user: Closure routes are not supported.

Skipping route: [GET] /: Closure routes are not supported.

Writing index.md and source files to: resources/docs

Wrote index.md and source files to: resources/docs

Generating API HTML code

Wrote HTML documentation to: public/docs

Generating Postman collection

Wrote Postman collection to: public/docs/collection.json

http://localhost/apilaravel/public/docs で、なんか画面っぽいものが出てきた～！

見にくいので、json読み込んでswagger uiで表示出来ないの？と思って読み込んだら、出力されたjsonファイルがバージョン２だった…。
swagger ui2.0で読み込んでも、なんか表示されない！

う～ん、php artisan route:list の出力を加工した方が早い気がしてきた…。

関連記事