blocs/docs: 処理機能記述書の自動生成（docsミドルウェア）

blocs/docs: 処理機能記述書の自動生成（docsミドルウェア）

docs ミドルウェアは、Laravelのコントローラーに記述した処理説明をもとに、Excel形式の処理機能記述書（IPO形式）を自動生成するツールです。手作業によるドキュメント作成を不要にし、開発効率を向上させます。

インストール

前提条件: Laravel プロジェクトがセットアップ済みであること。

composer require blocs/docs
cp -r vendor/blocs/docs/docs ./

docs/format.xlsx（テンプレート）と docs/common.php（共通設定）がプロジェクトの docs/ に配置されます。docs() ヘルパーはパッケージに同梱され、composer require で自動読み込みされます。

blocs/admin とは独立したパッケージです（No.1.1 参照）。

ドキュメント生成手順

1. コントローラーに処理説明を書く

docs() 関数で処理内容を順番に記述します。

class TestController extends Controller
{
    public function index()
    {
        docs('# 画面表示');
        docs('テンプレートを読み込んで、HTMLを生成');

        return view('welcome');
    }
}

2. ミドルウェアの設定

ドキュメントを生成したいルートに Blocs\Middleware\Docs::class を追加します。

Route::middleware(['web', 'auth', Blocs\Middleware\Role::class, Blocs\Middleware\Docs::class])
    ->prefix('admin/user')
    ->name('admin.user.')
    ->group(function () {
        ...
    });

3. ドキュメントの生成

設定したルートにアクセスすると、docs/format.xlsx をテンプレートとして docs/ フォルダに Excel ドキュメントが生成されます。出力ファイル名は docs/{コントローラー@メソッド}.xlsx 形式です（例: docs/Admin/[email protected]）。

• ドキュメントはルート（コントローラー×メソッド）ごとに生成
• 出力形式はIPO（Input: 入力、Process: 処理、Output: 出力）
• システム名・成果物名・作成者は docs/format.xlsx を編集して指定
• 画面名・メソッド概要は設定ファイルで指定
• 作成日・メソッド名は自動で出力

docs() 関数の使い方

見出しの書き方

# から始めると処理の見出しになります。

docs('# 画面表示');

処理内容の書き方

引数1つで処理機能として記録されます。配列で複数処理をまとめることも可能です。

docs('入力値を以下の条件で検証して、エラーがあればメッセージをセット');

docs([
    '<search>があれば、<'.$this->loopItem.'>のnameを<search>で部分一致検索',
    '<search>があれば、<'.$this->loopItem.'>のemailを<search>で部分一致検索',
    '<search>があれば、<'.$this->loopItem.'>のroleを<search>で部分一致検索',
]);

入力・出力の書き方

複数引数で「入力」「処理」「出力」を記述します。

• 第1引数: 入力（連想配列）
• 第2引数: 処理内容（文字列または配列）
• 第3引数: 出力（連想配列）

docs(['POST' => '入力値'], '入力値を以下の条件で検証して、エラーがあればメッセージをセット');

docs(null, 'エラーがあれば、ログイン画面に戻る', ['FORWARD' => 'admin.user.login']);

複数の入力・出力も指定できます。

docs(['POST' => '旧パスワード', 'データベース' => 'ユーザー管理'], '<旧パスワード>があれば、<ユーザー管理>をチェック');

バリデーション情報の記述（第4引数）

第4引数でバリデーション条件をドキュメントに記録できます。

docs(['POST' => '入力値'], '入力値を検証', ['FORWARD' => 'エラー画面'], ['name' => '必須', 'email' => 'メール形式']);

自動補完機能

ミドルウェアは以下の情報を自動的に補完します。

• 入力情報: 最終ステップに入力ドキュメントがない場合、レスポンスのテンプレートパスを「テンプレート」として自動設定
• 出力情報: 最終ステップに出力ドキュメントがない場合、HTMLの <title> タグの内容を「HTML」として自動設定

これにより、画面描画ステップの入出力ドキュメントを省略できます。

設定ファイルの書き方

• docs/common.php: 全コントローラー共通の設定
• docs/*Controller.php: コントローラー専用の設定（メソッド名をキーにしてメソッドごとの設定も可能）

設定ファイルの記述例

$config = [
    'description' => 'ユーザー管理画面',
    'keyword' => ['name' => '名前'],
    'neglect' => ['<名前>をセッションに保存'],
    'comment' => ['<名前>を表示' => 'フリガナも表示'],
    'index' => [
        'description' => '一覧画面表示',
    ],
];

QA

artisan コマンドの処理機能記述書を自動生成したい

ルートを追加してブラウザからアクセスします。

Route::get('/artisan', function () {
    \Artisan::call('summary:hotlog');
    return 'OK';
})->middleware(Blocs\Middleware\Docs::class);