最初にまとめ
OpenAPI Specification (OAS) × ChatGPT Images 2.0 を使うと、以下のような図解を簡単に作成できる、という小ネタです。
はじめに
OpenAPI Specification（OAS）は、APIの仕様を標準化し、API仕様そのものをドキュメントとして扱える強力なフォーマットです。
しかし正直なところ、
仕様書としては便利。でも、いきなり見ても戸惑う。
というのが本音ではないでしょうか。
Swagger や ReDoc などで閲覧する前提にはなりますが、これらが出力するのも、あくまで 仕様書 です。開発導入時に「これを読んでおいて」と渡されるのは、なかなかハードルが高いものがあります。（遠い目）
そこでChatGPT Images 2.0 を活用してみようという小ネタになります。
雑なプロンプトでも高い理解力で図解してくれるため、「OASを図解してと指示するだけです。」で、十分だったりしますが、デモとTipsもあわせて紹介。
お題「PetStore」
https://github.com/swagger-api/swagger-petstore/blob/master/src/main/resources/openapi.yaml/
いわゆる定番のサンプルです。
あくまでも仕様書
まずは Swagger と ReDoc を振り返りましょう。「OASがあるので読んでおいて」と言われたときに提示される、あの画面です。どちらも非常に優秀ですが、あくまで読み解くことが前提の仕様書です。やはり、初見で理解するにはハードルがあります。
Swagger UI : link
ReDoc : link
PetとStoreでAPIがいっぱいあることはわかった
一瞬でわかる開発導入ガイドの作り方
これらの仕様書を 一瞬でわかる資料 に変換するのが今回の目的です。
まずは成果物を再掲載。
どうでしょう。「完全に理解した」と言いたくなる説得力を感じませんか。
AIと対話したところ、人は順序よりも「配置」を認識することが得意で、言葉よりも「関係性」で理解する傾向があり、脳内で文章をイメージに翻訳する必要がなくなるため、直感的に理解しやいとか。このあたりは掘り下げても面白そうですね。
プロンプト「図解して」
では、実際に生成していきまます。
プロンプトは、 正直なんでもいい シンプルです。
このOpenAPI Specificationを、初心者でも理解できる図解にしてください。
※ 公開URLか、yaml全文を貼り付ける
結果
数十秒で生成されます。
これだけの指示で、この分かりやすさと理解度のある資料が出てきます。
修正も速い
さらに、好みに合わせた調整も簡単です。例えば以下のような指示をします。
- データモデルはリレーションを意識して
- 利用フローも含めて
結果
指示の意図を汲み取り素直に反映してくれます。そして、何より修正が非常に速いです。
また、レイアウトの再編成 をしてくれるのもポイントで、整理された図のまま維持されます。人には無理な芸当になっていますね。
※ 赤枠を、あえて引いてもらいまいした。
おまけ 画像から再利用可能なプロンプトを生成
好みの図解ができたら、それをベースに再利用可能なプロンプトも生成できます。
この画像は、OpenAPIから生成したものです。別のOpenAPIから生成する場合にも利用できるプロンプトを作成してください。
※ 画像を添付
結果
構造を文書として表現してくれるため、好みの部分だけを使い回すなども可能です。
以下のOpenAPI仕様（YAMLまたはJSON）をもとに、
初心者でも一目で理解できる「API概要図」を作成してください。
# 目的
・APIの全体像を直感的に理解できるようにする
・エンドポイント / データモデル / 利用フローを整理する
# 出力形式
・1枚の図としてまとまるレイアウト（インフォグラフィック風）
・セクションごとに整理されたビジュアル構成
・日本語で説明
# 必須構成
## 1. ヘッダー
・API名
・概要説明（1行）
・ベースURL
・OpenAPIバージョン
## 2. エンドポイント一覧（タグ別）
・タグ単位でグルーピング
・各エンドポイントに以下を表示
- HTTPメソッド（色分け）
- GET: 緑
- POST: 青
- PUT: オレンジ
- DELETE: 赤
- パス
- 概要（簡潔に）
## 3. 認証方式
・利用されている認証方式を図解
- API Key / OAuth2 / Bearer など
・リクエスト例（ヘッダ or クエリ）
## 4. データモデル（スキーマ + リレーション）
・主要エンティティを箱で表現
・以下を含める
- フィールド（型付き）
- 主キー相当の項目
・リレーションを線で表現
- 1対1
- 1対多
- 多対多
## 5. ステータスや状態（あれば）
・enum値を整理
・意味も補足
## 6. 利用フロー（典型シナリオ）
・実際の利用順に並べる
例：
1. 一覧取得
2. 詳細取得
3. 作成
4. 更新 / 状態確認
・矢印でつなぐ
## 7. レスポンス形式
・成功例
・エラー例
## 8. ポイントまとめ
・このAPIの特徴を3〜5個
# デザイン指示
・Swagger風 + インフォグラフィック風
・アイコンを適度に使用（ユーザー・注文・タグなど）
・ボックスと矢印で構造化
・視線が左→右、上→下に流れるように
・初心者向けにやさしい表現
# 入力OpenAPI
---
{{ここにOpenAPI仕様を貼る}}
---
ChatGPT Image2.0 の良い点と注意点
- 雑なプロンプトでも高い理解力で図解できる
- 修正指示に素直に対応してくれる
- レイアウトも再編成され整理された図が維持される
- とにかく生成スピードが速い
- ※利用回数に制限がある
指示の精度と生成速度から試行錯誤のコストが非常に低くく「最強」 と言いたくなるところですが、回数制限がネックです。無限に生成していたい。 ただし、理解力も高いため、ワンショットでも十分実用的な図解が得られることも多いかなと感じます。
また、今回のケースであれば、画像を無理にメンテナンスし続けるよりも、必要なタイミングで生成する運用の方が適しているかもしれません。図解の位置づけが変わっていきそうな気配。
まとめ
🤵「OASがあるので読んでおいてください。」
👱「OASがあるので図解してください。」
🤖「ワカリマシタ」