openapi-specification
OpenAPI仕様の専門スキル。API定義、スキーマ設計、ドキュメント生成を提供します。Anchors:• 『OpenAPI Specification』(Linux Foundation) / 適用: API仕様設計 / 目的: REST API標準化• 『RESTful API設計のベストプラクティス』(複数出典) / 適用: エンドポイント設計 / 目的: 一貫性確保Trigger:OpenAPI仕様書作成時、API定義ドキュメント作成時、Swagger仕様設計時に使用
When & Why to Use This Skill
This Claude skill provides comprehensive support for designing, creating, and validating OpenAPI 3.x specifications. It streamlines the RESTful API development lifecycle by automating endpoint design, schema definition, and security configuration. By integrating best practices and automated validation scripts, it ensures that your API documentation is consistent, secure, and fully compliant with industry standards.
Use Cases
- Case 1: Designing new RESTful API specifications from scratch using standardized templates to ensure consistent structure across info, servers, and paths.
- Case 2: Updating existing OpenAPI documents with automated impact analysis to prevent breaking changes and maintain backward compatibility.
- Case 3: Validating API syntax and security schemes using integrated scripts to identify and fix errors before deployment.
- Case 4: Standardizing complex data schemas and error handling responses across multiple microservices to improve developer experience and integration reliability.
| name | openapi-specification |
|---|---|
| description | | |
| • 『OpenAPI Specification』(Linux Foundation) / 適用 | API仕様設計 / 目的: REST API標準化 |
| • 『RESTful API設計のベストプラクティス』(複数出典) / 適用 | エンドポイント設計 / 目的: 一貫性確保 |
OpenAPI Specification スキル
概要
OpenAPI 3.x仕様に準拠したAPI仕様書の設計と作成を専門とするスキル。RESTful APIの設計原則に基づいて、セキュアで保守性の高いAPI仕様書を作成します。エンドポイント設計、スキーマ定義、認証・認可設定、エラーハンドリング、およびドキュメント生成を統合的に実施します。
詳細な手順や背景は references/ ディレクトリを参照してください。
ワークフロー
Phase 1: 要件定義
目的: API仕様の要件を明確化
アクション:
references/basics.mdでOpenAPI基本構造を確認- エンドポイント数、認証方式、レート制限を定義
- 既存API仕様の有無を確認(更新か新規作成か判定)
Phase 2: 仕様設計
目的: OpenAPI仕様書を設計・作成
アクション:
agents/design-api.mdを参照して設計を実施assets/openapi-base-template.yamlをベースに仕様書を作成references/schema-design-patterns.mdでスキーマ設計references/security-schemes.mdでセキュリティ構成
Task: agents/design-api.md を参照
Phase 3: 検証
目的: 仕様書の検証と記録
アクション:
agents/validate-spec.mdを参照して検証を実施scripts/validate-openapi.mjsで構文チェック- セキュリティ設定とベストプラクティスを確認
Task: agents/validate-spec.md を参照
Task仕様(ナビゲーション)
| Task | 起動タイミング | 入力 | 出力 |
|---|---|---|---|
| design-api | Phase 2開始時 | API要件 | 仕様書ドラフト |
| validate-spec | Phase 3開始時 | 仕様書ドラフト | 検証済み仕様書 |
詳細仕様: 各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/(詳細知識)
| リソース | パス | 用途 |
|---|---|---|
| 基礎知識 | See references/basics.md | OpenAPI基本構造 |
| 構造ガイド | See references/openapi-structure.md | 全セクション仕様 |
| スキーマパターン | See references/schema-design-patterns.md | スキーマ設計 |
| セキュリティ | See references/security-schemes.md | 認証・認可設定 |
assets/(テンプレート)
| リソース | パス | 用途 |
|---|---|---|
| ベーステンプレート | assets/openapi-base-template.yaml |
仕様書ベース |
| エンドポイント | assets/endpoint-template.yaml |
個別パス定義 |
変更履歴
| Version | Date | Changes |
|---|---|---|
| 1.2.0 | 2026-01-02 | agents/追加、Level構造を統合 |
| 1.1.0 | 2025-12-31 | 18-skills.md仕様に準拠 |
| 1.0.0 | 2025-12-24 | 初期実装 |