openapi-spec-generation

openapi-spec-generation スキルの概要

openapi-spec-generation スキルでできること

openapi-spec-generation スキルは、場当たり的なプロンプトに頼るのではなく、実績あるパターンに沿って OpenAPI 3.1 の API 仕様を作成・改善できるようにするスキルです。単なる YAML のたたき台ではなく、ドキュメント、クライアント SDK 生成、バリデーション、API ガバナンスに使える“実用的な契約”が必要なチームに向いています。

どんな人・チームに向いているか

このスキルが特にフィットするのは、次のようなケースです。

• 既存の REST API を文書化したいバックエンドチーム
• サービス横断で契約を標準化したいプラットフォームチーム
• code-first フレームワークから、より整理された仕様へ移行したい開発者
• SDK 生成、モックサーバー、契約チェックの準備を進めたいチーム

重視しているのは「OpenAPI とは何か？」の説明ではなく、「抜け漏れの少ない、信頼できる仕様をどう作るか」です。

実際に解決したい仕事

多くのユーザーが欲しいのは、単に openapi.yaml という名前のファイルではありません。必要なのは、次の用途に十分耐えられる仕様です。

• 実際のリクエスト／レスポンスの形を正しく表現する
• 認証、エラー、ページネーション、共通ヘッダーをモデル化する
• 後続ツールでそのまま活用できる
• API の変更に合わせて保守しやすい

openapi-spec-generation スキルが役立つのは、汎用的な API 説明文ではなく、OpenAPI 3.1 の構造、設計アプローチの選択、具体的なテンプレートへと作業を寄せてくれるからです。

このスキルの差別化ポイント

通常の「OpenAPI spec を書いて」というプロンプトと比べると、このスキルはエージェントに対して次のものを明示的に与えます。

• OpenAPI 3.1 を前提にした枠組み
• design-first、code-first、hybrid の各ワークフローに対するガイダンス
• 完全な仕様書に使える再利用可能なテンプレート
• 同梱の references/code-first-and-tooling.md にある code-first の実践例

そのため、実装の事情と契約品質の両立が求められる openapi-spec-generation for API Development のような用途で特に有効です。

インストール前に確認したいこと

openapi-spec-generation skill を採用する前に、自分たちの主目的が次のどれかを整理しておくとスムーズです。

• プロダクト要件から新しい契約を起こしたい
• 既存コードから契約を抽出したい
• すでにある仕様を引き締めたい

API が強い RPC スタイルだったり、イベント駆動中心だったり、REST 指向ではない場合は、このスキルをそのまま使うより、調整を前提に使うほうが現実的です。

openapi-spec-generation スキルの使い方

openapi-spec-generation のインストール文脈

親スキルコレクションをインストールしたうえで、エージェントのワークフローから openapi-spec-generation を呼び出します。

npx skills add https://github.com/wshobson/agents --skill openapi-spec-generation

このスキルは wshobson/agents リポジトリの plugins/documentation-generation/skills/openapi-spec-generation にあります。

最初に読むべきファイル

最短で全体像をつかむなら、まず次を確認してください。

1. plugins/documentation-generation/skills/openapi-spec-generation/SKILL.md
2. plugins/documentation-generation/skills/openapi-spec-generation/references/code-first-and-tooling.md

SKILL.md には主な対象範囲とテンプレートがまとまっています。参照ファイルには、より実務寄りの code-first パターンが載っており、アプリケーションコードが source of truth の場合に特に役立ちます。

openapi-spec-generation で最初の進め方を選ぶ

このスキルには、実務上使いやすい 3 つの入口があります。

• Design-first: 新規 API や、実装前に契約レビューしたいケースに最適
• Code-first: FastAPI のようなフレームワークですでに API が存在する場合に最適
• Hybrid: コードはあるが、公開契約としてはもう少し整理された形にしたい場合に最適

この選択は、多くの人が思う以上にプロンプト品質へ影響します。ここを飛ばすと、出力が曖昧になったり、内部整合性が崩れたりしがちです。

openapi-spec-generation に必要な入力

openapi-spec-generation usage が最も力を発揮するのは、次のような具体的な API 情報を渡したときです。

• メソッドと path params を含むルート一覧
• リクエスト／レスポンス JSON の例
• 認証モデル
• ページネーション方式
• 主要なエラーケース
• エンティティスキーマやバリデーションモデル
• 環境／サーバー URL
• 命名規則とバージョニングルール

「ユーザー API の spec を生成して」だけだと、テンプレート色の強いドラフトになりやすく、実際の契約としてはまだ詰めが必要です。

ざっくりした目的を強いプロンプトに変える

弱いプロンプト:

• “Generate an OpenAPI spec for a user service.”

より強いプロンプト:

• “Use the openapi-spec-generation skill to create an OpenAPI 3.1 spec for a REST API with GET /users, POST /users, GET /users/{id}, and PATCH /users/{id}. Auth is bearer token. Users have id, email, name, status, and createdAt. Use cursor pagination on list endpoints, include standard 400/401/404/409 responses, model reusable schemas under components, and produce a clean spec suitable for SDK generation.”

後者のように構造を与えると、このスキルは単なるプレースホルダーではなく、契約として使える仕様を出しやすくなります。

既存 API でのベストな進め方

既存サービスに対して実践的な openapi-spec-generation guide を使うなら、次の流れが有効です。

1. コードやルーター定義からルートを棚卸しする。
2. リクエストモデル、レスポンスモデル、enum、バリデーションを抽出する。
3. フレームワークが生成するドキュメントをベースラインにするか、単なる参照にとどめるかを決める。
4. それらを OpenAPI 3.1 に正規化するようスキルに依頼する。
5. 抜けているエラーレスポンス、認証詳細、例、スキーマ再利用をレビューする。
6. 最後に自前のバリデーションや linting ツールをかける。

不完全な記憶だけを頼りに、一発でフル spec を作らせるより、この進め方のほうが安定します。

新規 API でのベストな進め方

新規 API では、次の順序が効果的です。

1. まずリソースと操作を定義する。
2. バージョニング、認証、ページネーションの方針を決める。
3. 再利用可能な components を含む design-first の spec 作成をスキルに依頼する。
4. 実装に入る前に、命名の一貫性とエラーモデルを確認する。
5. 合意した spec をそのまま実装契約として使う。

コードが存在する前なら、契約のミスを安く直せるため、このスキルの効果が特に大きく出ます。

code-first 参照ファイルをうまく使う

同梱の references/code-first-and-tooling.md は、Python や TypeScript 系の開発で特に参考になります。そこでは、より良い source material の条件が具体的に示されています。

• typed models
• enum の使い方
• バリデーションメタデータ
• フレームワークレベルの説明と tags
• server 定義

これは重要です。というのも、code-first の OpenAPI 生成品質は、コード側でどれだけドメインが適切にモデル化されているかに大きく左右されるからです。

openapi-spec-generation の良い出力に含まれるべきもの

openapi-spec-generation skill の良い成果物には、通常は次の要素が入っているべきです。

• openapi: 3.1.0
• 明確な info メタデータ
• 現実的な servers
• 完整な paths
• 再利用可能な components.schemas
• security schemes
• 共通化されたレスポンス／エラー処理
• 曖昧さが採用障壁になる箇所の examples

これらが欠けているなら、後続ツールに渡すにはまだ早い状態です。

リポジトリを読むときの実用的な順番

スキルを本格的に使う前に upstream の中身を確認したいなら、次の順で見るのがおすすめです。

• SKILL.md をざっと見て、対象範囲・構造・テンプレートを把握する
• references/code-first-and-tooling.md を開いて、実装寄りの例を確認する
• 自分たちのフレームワークや現在の API 成熟度と、その例を照らし合わせる

この repo は比較的軽量なので、価値の中心は自動化スクリプトではなく、プロンプト設計の足場と具体例にあります。

出力品質を上げる実践的なコツ

• プレースホルダーではなく、実際のフィールド名を渡す
• nullable を許可するか明記する
• 実際に使っているエラーコードを列挙する
• ID が UUID、整数、opaque strings のどれかを指定する
• list endpoint のページネーションが cursor、page/size、offset/limit のどれかを伝える
• どのスキーマを endpoint 間で共有したいか伝える

こうした情報があるだけで、後工程の手直しは大幅に減ります。

openapi-spec-generation スキル FAQ

openapi-spec-generation は初心者にも向いている？

はい。少なくとも自分の API を理解しているなら有効です。このスキルは spec の構造化を助けてくれますが、endpoint、認証、データモデルの理解そのものを肩代わりするものではありません。API の棚卸しができていない初心者だと、十分な入力情報を出せず苦戦することがあります。

普通の OpenAPI プロンプトより良い？

多くの場合は yes です。openapi-spec-generation skill は、OpenAPI 3.1、設計アプローチの選択、実践的なテンプレートを中心に据えているため、汎用プロンプトより出発点が良くなります。差が出るのは創造性というより、完全性と一貫性です。

コードから直接 spec を生成できる？

自動で repo を走査して生成するタイプではありません。code-first 生成のためのパターンや例は、特に参照ファイルを通じて提供していますが、関連するコード文脈や抽出済み endpoint 情報は、こちらでエージェントに渡す必要があります。

openapi-spec-generation が向かないのはどんなとき？

次のような場合は適合度が下がります。

• API が REST らしい構造ではない
• 大規模コードベースからの完全自動抽出が必要
• 主な課題が契約作成ではなく実行時テストである
• spec 執筆ガイダンスより、フレームワーク固有のツール設定が必要

こうしたケースでは、専用ジェネレーターやフレームワークネイティブなツールを主軸にしたほうが適しています。

既存 spec の保守にも使える？

使えます。openapi-spec-generation は、不完全な spec を引き締めたり、OpenAPI 3.1 に寄せたり、不足している再利用 components、responses、ドキュメント構造を補ったりするのに向いています。

SDK 生成ワークフローにも適している？

はい。ただし、結果のレビューは必須です。SDK 生成は、スキーマ品質、enum の表現、operation IDs、認証定義、レスポンスの一貫性に強く依存します。このスキルはそれらの下書きを助けますが、最終的な検証責任までは引き受けません。

openapi-spec-generation スキルを改善するには

契約レベルの入力を openapi-spec-generation に渡す

openapi-spec-generation の結果を最も速く改善する方法は、機能レベルの依頼をやめて、契約レベルの依頼に切り替えることです。含めるべき情報は次のとおりです。

• 正確な endpoint
• 必須／任意フィールド
• enum 値
• payload の例
• status codes
• 認証ルール
• 再利用できるオブジェクト形状

これだけで、出力は「spec っぽい文章」から、かなり本番投入に近いものへ変わります。

足りないセクションは明示的に要求する

初稿では、運用上重要な要素が抜けることがよくあります。必要なら次の項目を明示的に含めるよう依頼してください。

• security schemes
• pagination parameters
• error response schema
• operation IDs
• 再利用可能な request bodies
• tags と descriptions
• 誤解しやすいフィールドの examples

汎用的な spec ドラフトは、このあたりを薄くしがちなので、はっきり要求する価値があります。

code-first ワークフローでの schema drift を防ぐ

既存サービスに対して openapi-spec-generation for API Development を使うなら、最大のリスクは schema drift です。次の情報を渡してズレを減らしてください。

• 現在の model 定義
• バリデーション制約
• route handlers や controller signatures
• 実装と docs の既知の差分

これがないと、実 API より整いすぎた契約が出ることがあります。編集上は見栄えが良くても、運用上は危険です。

一発勝負ではなく、段階的に回す

より良い進め方は次のとおりです。

1. 骨組みを生成する
2. schemas を詰める
3. auth と errors を詰める
4. examples を追加する
5. 命名と再利用を標準化する

中規模 API 以上では、こうしたパス分けの進め方のほうが、巨大な単発プロンプトよりたいてい安定します。

よくある失敗パターンをチェックする

初回出力でありがちな問題は次のとおりです。

• 実務価値の低い、一般論的な descriptions
• 不足した error models
• paths と schemas の命名不一致
• 十分に定義されていないリクエストバリデーション
• create・update・read モデルの区別が曖昧
• schema 制約と一致しない examples

いずれも修正は可能ですが、実 API の挙動を踏まえてレビューしなければ見逃しやすい点です。

参照ファイルをプロンプトの材料として使う

実務で openapi-spec-generation guide の精度を上げる簡単な方法は、references/code-first-and-tooling.md にある構成や情報密度に合わせるようエージェントへ伝えることです。特に効くのは次の観点です。

• typed schemas
• enum handling
• validation metadata
• server definitions
• model descriptions

「ちゃんと完全なものにして」とだけ言うより、はるかに強い指示になります。

生成後は必ず検証する

出来の良いドラフトでも、普段使っている OpenAPI validator、linter、下流の generator で確認するべきです。このスキルは最初の版を良くしてくれますが、検証の代わりにはなりません。特に docs portal、code generation、contract testing に流す場合は重要です。

openapi-spec-generation の出力はスコープを絞ると改善しやすい

最初の試行が散らかるようなら、依頼範囲を狭めてください。

• 1 リソースずつ
• 1 つの path グループずつ
• 1 つの schema ファミリーずつ

そのうえで、レビュー済みの断片を最後にマージします。多くのチームでは、これが本番作業で openapi-spec-generation usage を安定して使ういちばん確実な方法です。