---
title: 「Scramble」を使ってみた
tags: 
author: [Kou](https://www.docswell.com/user/kou_tech)
site: [Docswell](https://www.docswell.com/)
thumbnail: https://bcdn.docswell.com/page/47ZK9G8L73.jpg?width=480
description: 「Scramble」を使ってみた by Kou
published: February 10, 25
canonical: https://www.docswell.com/s/kou_tech/ZMXY3X-2025-02-10-192929
---
# Page. 1

![Page Image](https://bcdn.docswell.com/page/47ZK9G8L73.jpg)

Laravel向け
OpenAPIドキュメントジェネレーター
「Scramble」を使ってみた
2025/02/08 札幌PHP勉強会
Kou


# Page. 2

![Page Image](https://bcdn.docswell.com/page/YJ6QKYPMJV.jpg)

自己紹介
🦌 Kou (@kou_tech_1017)
💻 プログラマー
PHP、React、Azure
Sapporo Engineer Base運営


# Page. 3

![Page Image](https://bcdn.docswell.com/page/GJ5RPGKQ74.jpg)

今日話すこと
主に「OpenAPI」について話します


# Page. 4

![Page Image](https://bcdn.docswell.com/page/9E2D6YWWER.jpg)

「OpenAPI」はご存知ですか？


# Page. 5

![Page Image](https://bcdn.docswell.com/page/D7Y29GL97M.jpg)

「OpenAPI」とは、
RESTful APIの設計とドキュメント化
のための標準仕様


# Page. 6

![Page Image](https://bcdn.docswell.com/page/VEN8LG4DJ8.jpg)



# Page. 7

![Page Image](https://bcdn.docswell.com/page/Y79K4WQ873.jpg)

OpenAPIの利点
Gitなどのバージョン管理ツールと親和性があり、変更
履歴や差分管理が容易である
常に最新の仕様を全員で共有できる
スキーマに基づいて効率的な分業開発が可能となる


# Page. 8

![Page Image](https://bcdn.docswell.com/page/G78RQNGZED.jpg)

OpenAPIの不利点
学習コストが必要となる
OpenAPIのスキーマの範囲外での柔軟な操作や部分的
なレスポンス制御が複雑になる
仕様書の管理には専用ツールやエコシステムが必須と
なることが多い
Apidog、Stoplight


# Page. 9

![Page Image](https://bcdn.docswell.com/page/L7LKXPG1ER.jpg)

負のスパイラル
1. 設計書の手動管理はメンテナンスが大変
2. 情報の更新が追いつかず、古くなる
3. 仕様書がコードと乖離し、開発に影響を
与える


# Page. 10

![Page Image](https://bcdn.docswell.com/page/4EM2L4Q5EW.jpg)

Laravelのコードから
自動生成できないかな...


# Page. 11

![Page Image](https://bcdn.docswell.com/page/PERMKW8Z79.jpg)

今回紹介するのが...


# Page. 12

![Page Image](https://bcdn.docswell.com/page/P7XVLP81JX.jpg)

Scramble


# Page. 13

![Page Image](https://bcdn.docswell.com/page/37KQLDKM7D.jpg)

Scrambleとは
Laravel用のOpenAPIドキュメントを自動生成
するツール
コードから直接APIドキュメントを生成できる
Stoplight ElementsでUI表示ができる
https://scramble.dedoc.co/


# Page. 14

![Page Image](https://bcdn.docswell.com/page/LJ3P3RZ275.jpg)

Scrambleの主な特徴
静的コード解析とLaravelの規約を活用して、APIドキ
ュメントを自動生成
リクエスト・レスポンス・エラーをすべて自動でドキ
ュメント化
アノテーションは必須ではなく、必要なときだけ追加


# Page. 15

![Page Image](https://bcdn.docswell.com/page/8JDL4YR67G.jpg)

他のライブラリとの比較
例 ) ユーザー一覧を取得するAPI


# Page. 16

![Page Image](https://bcdn.docswell.com/page/VEP2M6MZE8.jpg)

l5-swagger
PHPDocアノテーションを使用して、APIドキュメントを記
述する
アノテーションが冗長で、メンテナンスが大変
フィールドの追加・変更時にアノテーションの修正が必要
コードのノイズが増える


# Page. 17

![Page Image](https://bcdn.docswell.com/page/27VD939M7Q.jpg)



# Page. 18

![Page Image](https://bcdn.docswell.com/page/5JGYZ3ZXJL.jpg)

Laravel-OpenAPI
Laravel-OpenAPIでは、アトリビュート（Attributes）
を使ってAPI仕様を記述する
設定が煩雑
仕様変更時にコードの修正が必要になる
ドキュメントのためのコードが増え、可読性が下がる


# Page. 19

![Page Image](https://bcdn.docswell.com/page/47QML5L5EP.jpg)



# Page. 20

![Page Image](https://bcdn.docswell.com/page/KE4VD9DV71.jpg)

Scrambleだと...


# Page. 21

![Page Image](https://bcdn.docswell.com/page/L713ZKZ4EG.jpg)

これだけ！！


# Page. 22

![Page Image](https://bcdn.docswell.com/page/G7WP9D9ZE2.jpg)

Scrambleだと
コードベースから仕様書を自動生成する
記述量が圧倒的に少ない
メンテナンスも容易


# Page. 23

![Page Image](https://bcdn.docswell.com/page/4JZK9G9LJ3.jpg)

デモ


# Page. 24

![Page Image](https://bcdn.docswell.com/page/YE6QKYKMEV.jpg)

所感
実際に活用する場合、Scrambleは型推論を活用して自動生
成してくれるものの、完全にアノテーション不要というわ
けではなく、一部手動記述をする運用になりそう。
例）APIの詳細な説明、具体的な値、セキュリティスキームの追加など


# Page. 25

![Page Image](https://bcdn.docswell.com/page/GE5RPGPQJ4.jpg)

注意
本来の開発プロセスでは、詳細な設計書を作成
して実装に移行するのが一般的
コードファーストとした設計書はそれで別の課
題が残る


# Page. 26

![Page Image](https://bcdn.docswell.com/page/972D6Y6W7R.jpg)

まとめ
ScrambleはLaravelでのOpenAPI仕様書管理を圧倒的に効
率化するツールである。
仕様書管理に悩んだり、分業開発の現場において、
ドキュメントの自動生成を導入する利点は大きい。


# Page. 27

![Page Image](https://bcdn.docswell.com/page/DJY29G99JM.jpg)

ご清聴ありがとうございました