【Laravel】ドキュメント生成ツールを作ってみた

:::note info
この記事は、Laravelで使えるプログラム処理内容の説明ドキュメント（処理機能記述書）生成ツールの紹介です。
:::

# はじめに
PHPer皆さん、ドキュメント書いてますか？処理フロー確認やレビュー、他人が作ったプログラムの理解を深めるためにドキュメントは大きな助けになります。一方で、Excelでドキュメントを作ってくださいとか、プログラム変更時にメンテナンスしなければいけないとか、とにかくメンドくさいですよね。このメンドくさいを減らすために、コントローラーに処理説明を書くだけでExcelドキュメント（処理機能記述書）を生成するツールを開発しました。
![スクリーンショット 2024-06-21 23.59.27.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2962814/ecd4ad52-8fe8-b7e1-f201-e3fe55844d71.png)

# 仕組み
Laravelのコントローラーに、コメントのような処理説明を書いて実行する（画面を表示するなど）とミドルウェアがExcelドキュメントを生成します。
![スクリーンショット 2024-06-20 21.18.00.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2962814/73d24bb0-ed7b-60f7-1069-215244a3b5e5.png)

# 準備

## 1. インストール
Laravelがインストールされている環境に、composerでインストールしてください。

https://github.com/blocs/docs

:::note info
composer require blocs/docs
:::

## 2. docsをコピー
`vendor/blocs/docs` の下の `docs` をLaravelのルートにコピーします。`docs/format.xlsx` がフォーマットExcelで、`common.php` や `*Controller.php` が設定ファイルです。
![スクリーンショット 2024-06-20 20.33.01.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2962814/8f786715-d9f0-c77b-e0fb-99ab70be5f27.png)

# ドキュメント生成

## 1. 処理説明を書く
`docs()` で、コントローラーに処理説明を書きます。処理説明を実行した順にドキュメントに出力します。
```php:app/Http/Controllers/TestController.php
class TestController extends Controller
{
    public function index()
    {
        docs('# 画面表示');
        docs('テンプレートを読み込んで、HTMLを生成');

        return view('welcome');
    }
}
```

## 2. ルーティング
ドキュメントを生成したいルートの `middleware` に `Blocs\Middleware\Docs::class` を設定します。
```php:routes/web.php
Route::get('/', [TestController::class, 'index'])->middleware(Blocs\Middleware\Docs::class);
```

ミドルウェアのエイリアスを指定しておくと、簡単にミドルウェアを設定できます。
```php:bootstrap/app.php（Laravel11）
    ->withMiddleware(function (Middleware $middleware) {
        $middleware->alias([
            'docs' => Blocs\Middleware\Docs::class
        ]);
    })
```

```php:routes/web.php
Route::get('/', [TestController::class, 'index'])->middleware('docs');
```

## 3. ドキュメント生成
`middleware` を設定したルートにアクセスすると、`docs/format.xlsx` を使って `docs` にExcelドキュメントを生成します。Excelドキュメントはルートごとに生成します。
![スクリーンショット 2024-06-22 0.14.53.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2962814/7352b854-cdd1-3364-a7ca-350ee49161d8.png)

ドキュメントは、IPO（Input: 入力、Process: 処理機能、Output: 出力）形式で出力します。システム名、成果物名、作成者は `docs/format.xlsx` を編集して指定します。画面名、メソッド概要は設定ファイルで指定します。作成日、メソッドは自動で出力されます。
![スクリーンショット 2024-06-22 0.19.28.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2962814/ceecfe6a-28c7-6f52-736e-401af904c61b.png)

# docsの書き方
`# 画面表示` のように `#` から始めると、処理の見出しになります。

```php
docs('# 画面表示');
```
![スクリーンショット 2024-06-22 22.14.25.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2962814/80da9999-2ce7-a2fa-d98e-d8f2c1791115.png)

`docs` の引数が1つの時は処理機能、引数が複数の時は入力、処理機能、出力になります。入力、出力は連想配列で指定します。複数の処理機能を配列で指定することもできます。

```php
docs(['POST' => '入力値'], '入力値を以下の条件で検証して、エラーがあればメッセージをセット');
```
![スクリーンショット 2024-06-22 22.15.05.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2962814/76f33462-cbff-4caa-e72e-307cd4d8864a.png)

```php
docs(null, 'エラーがあれば、ログイン画面に戻る', ['FORWARD' => 'admin.user.login']);
```
![スクリーンショット 2024-06-22 22.15.46.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2962814/9ae318c8-6c1d-3c6b-1acb-91a8d2fa421d.png)

複数の入力(例：POSTとデータベース)、出力を指定することもできます。

```php
docs(['POST' => '旧パスワード', 'データベース' => 'ユーザー管理'], '<旧パスワード>があれば、<ユーザー管理>をチェック');
```
![スクリーンショット 2024-06-22 22.16.12.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2962814/60508982-0172-0288-946d-aa9f7b390577.png)

# 設定ファイルの書き方
設定ファイルでキーワード置換や非表示の指定ができます。`common.php` は全コントローラー共通の設定ファイル、`*Controller.php` はコントローラーごとの設定ファイルです。`*Controller.php` にメソッドごとの設定も書けます。

|設定項目|説明|サンプル|
|---|---|---|
|description|画面名、メソッド概要|'description' => 'テスト画面'|
|keyword|テーブル名、項目名など置換するキーワード|'keyword' => ['name' => '名前']|
|neglect|非表示|'neglect' => ['<名前>をセッションに保存']|
|comment|追加コメント|'comment' => ['<名前>を表示' => 'フリガナも表示']|

```php:docs/TestController.php
$config = [
    'description' => 'テスト画面',
    'keyword' => ['name' => '名前'],
    'neglect' => ['<名前>をセッションに保存'],
    'comment' => ['<名前>を表示' => 'フリガナも表示'],
    'index' => [
        'description' => '一覧画面表示',
    ],
];
```

```php:app/Http/Controllers/TestController.php
docs('<name>を取得');
docs('<name>をセッションに保存');
docs('<name>を表示');
```
![スクリーンショット 2024-06-22 23.22.54.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2962814/1befb5df-a2c1-236d-07cc-8af462f58cd6.png)

# おわりに
最後まで読んでいただき、ありがとうございました。
いつもドキュメント作成はメンドーだなと感じていたので、ドキュメント生成ツールを作ってみました。このツールがPHPer皆さんのドキュメント作成をサポートできればいいなと思っています。

# 関連サイト
1. [GitHub](https://github.com/blocs/docs)
2. [Packagist](https://packagist.org/packages/blocs/docs)
3. [サービスサイト](https://blocs.jp)