OpenAPI Specification スキル

概要

OpenAPI 3.x仕様に準拠したAPI仕様書の設計と作成を専門とするスキル。RESTful APIの設計原則に基づいて、セキュアで保守性の高いAPI仕様書を作成します。エンドポイント設計、スキーマ定義、認証・認可設定、エラーハンドリング、およびドキュメント生成を統合的に実施します。

詳細な手順や背景は references/ ディレクトリを参照してください。

ワークフロー

Phase 1: 要件定義

目的: API仕様の要件を明確化

アクション:

1. references/basics.md でOpenAPI基本構造を確認
2. エンドポイント数、認証方式、レート制限を定義
3. 既存API仕様の有無を確認（更新か新規作成か判定）

Phase 2: 仕様設計

目的: OpenAPI仕様書を設計・作成

アクション:

1. agents/design-api.md を参照して設計を実施
2. assets/openapi-base-template.yaml をベースに仕様書を作成
3. references/schema-design-patterns.md でスキーマ設計
4. references/security-schemes.md でセキュリティ構成

Task: agents/design-api.md を参照

Phase 3: 検証

目的: 仕様書の検証と記録

アクション:

1. agents/validate-spec.md を参照して検証を実施
2. scripts/validate-openapi.mjs で構文チェック
3. セキュリティ設定とベストプラクティスを確認

Task: agents/validate-spec.md を参照

Task仕様（ナビゲーション）

詳細仕様: 各Taskの詳細は agents/ ディレクトリの対応ファイルを参照

ベストプラクティス

すべきこと

• 新規OpenAPI仕様書を作成する時: openapi-base-template.yaml をテンプレートとして使用し、info、servers、paths、componentsの全セクションを網羅する
• 既存OpenAPI仕様書を更新する時: 変更前後の仕様差異を明確にし、破壊的変更がないか検証する
• エンドポイントやスキーマを設計する時: schema-design-patterns.md と openapi-structure.md を参照して一貫性を保つ
• OpenAPI構文エラーを解決する時: validate-openapi.mjs で具体的なエラー箇所を特定してから修正する
• セキュリティスキームを設定する時: security-schemes.md のベストプラクティスを遵守し、全エンドポイントに適切な認証を適用する
• Level別の学習: 基礎（Level1）→実務（Level2）→応用（Level3）→専門（Level4）の順で進める
• 版管理: API仕様の更新履歴をCHANGELOG.mdで記録し、ユーザーに影響を通知する

避けるべきこと

• アンチパターンや注意点を確認せずに進めることを避ける
• セキュリティスキーム設定を後付けしない（設計段階から組み込む）
• 複数のエンドポイント間で不一貫なスキーマ定義を避ける
• エラーレスポンスの定義をスキップしない
• required フィールドの指定を曖昧にしない
• セキュリティ関連の設定をハードコード化しない（環境ごとに切り替え可能にする）
• OpenAPI仕様の検証をスキップして本番環境にデプロイしない

リソース参照

references/（詳細知識）

assets/（テンプレート）

変更履歴