Zenn
🐙

dedoc/scrambleを使ってLaravel API仕様書生成からの後付けスキーマ駆動開発

2025/03/13に公開
Laravel
Swagger
OpenAPI
tech

OpenAPIジェネレートしてTypeScriptコードを出力する

このブログではOpenAPIの仕様書をどうやって作るかについて何度も記事にしている。
ただ、基本的には仕様書をどうやって楽に作るかという視点で語っているが、
もし全部仕様書を作ってくれるなら？

(´・ω・｀) そんな都合のいいつーるがあるわけ、

dedoc/scramble

(;´･ω･) あるの？

LaravelのRequestやResponseなどを解析して仕様書を作ってくれるツール
jsonファイルが一つ生成されるのでそこからswagger-cliを使って各種コードを生成する

ヾ(・ω<)ﾉ"　三三三●　ⅱⅲ コロコロ♪

------------------- ↓ 本題はここから ↓-------------------

インストール

PHP Cli

以下はPHPのCliが動くことを前提にしているが、
docker経由でも動かすことができる
php を以下のコマンドに置き換えると実行できる

docker run --rm -it -v $(pwd):/app -w /app php:8.3-cli-alpine php

Homebrewを用意

swagger-cliがjavaで動くのでjavaを用意することになるが、
まとめてインストールしてくれるのでhomebrewを使う
macを使う人はすでにあるので次へ

Homebrewインストール(Linux)
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

シェルを起動しなおして以下のようになればOK

Homebrew Version
brew --version
  Homebrew 4.4.16

openapi-generatorのインストール

swagger-cliの一つopenapi-generatorをインストール

openapi-generatorインストール
brew install openapi-generator openjdk@11

dedoc/scrambleのインストール

あとはcomposerでdedoc/scrambleパッケージを追加する

dedoc/scrambleインストール
composer require dedoc/scramble

--devでインストールすると定義が本番で使えなくなってしまうので、
本番ビルドに載るようにすること
あとバージョンアップは頻繁に行われているので、
バージョン指定はきっちりする方がよい

仕様書生成

公式が用意しているデモプロジェクトを使って、
仕様書を作成する。
とりあえずcloneしてLaravelプロジェクトを動くようにする

https://github.com/dedoc/demo-scramble

git clone https://github.com/dedoc/demo-scramble.git
cd demo-scramble
cp .env.example .env
wget https://getcomposer.org/download/latest-stable/composer.phar
php composer.phar install
php artisan migrate

dedoc/scrambleを使って仕様書を生成する
以下のコマンドを実行

scramble
php artisan scramble:export --path=[ファイル名]

先ほどのプロジェクトで実際に仕様書を生成してみる

php artisan scramble:export --path=./api.json

VSCode(OpenAPI (Swagger) Editor)で見てみると

(^_-)-☆ なかなかいい感じ

TypeScriptコード生成

先ほど作成したjson仕様書からTypeScriptコードを生成する

openapi-generator generate -i api.json -o ./resources/js/ -g typescript-fetch
・・・
################################################################################
# Thanks for using OpenAPI Generator.                                          #
# Please consider donation to help us maintain this project 🙏                 #
# https://opencollective.com/openapi_generator/donate                          #
###############################################################################

VSCodeで確認

('ω')ノ ええやん！

------------------- ↓ 後書きはここから ↓-------------------

OpenApi generatorについてはいろいろあるようで、
ほかのジェネレータの方がいいという話は聞いている。

https://orval.dev

いいのがあれば教えてほしいやも。

Discussion