api-documentation-best-practices
OpenAPI、Swagger、RESTful APIドキュメンテーションのベストプラクティスを提供する専門スキル。Anchors:• 『RESTful Web APIs』(Leonard Richardson)/ 適用: REST APIドキュメンテーション / 目的: リソース設計とHTTP操作の標準化Trigger:OpenAPI/Swagger定義設計時、APIエンドポイント仕様書作成時、REST APIドキュメント整備時、認証仕様文書化時、エラーレスポンス標準化時、ドキュメントレビュー時に使用
When & Why to Use This Skill
This Claude skill provides expert-level guidance and best practices for OpenAPI, Swagger, and RESTful API documentation. It streamlines the API lifecycle by offering standardized templates for resource design, HTTP operations, authentication flows, and error handling, ensuring high-quality, developer-friendly documentation that aligns with industry standards like Leonard Richardson's 'RESTful Web APIs'.
Use Cases
- Designing OpenAPI/Swagger definitions: Use the skill to ensure API specifications are valid, follow standard formats, and are compatible with SDK generation tools.
- Standardizing API Endpoint Specifications: Apply resource-oriented design principles and use provided templates to create consistent documentation for complex endpoints.
- Documenting Authentication & Security: Implement best practices for documenting OAuth2, JWT, and other authentication flows to reduce security risks and implementation errors.
- Error Response Standardization: Define unified error structures and HTTP status codes to improve the developer experience for API consumers.
- API Documentation Review & Validation: Conduct automated and manual reviews of existing documentation to identify anti-patterns and ensure synchronization with the actual codebase.
| name | api-documentation-best-practices |
|---|---|
| description | | |
| • 『RESTful Web APIs』(Leonard Richardson)/ 適用 | REST APIドキュメンテーション / 目的: リソース設計とHTTP操作の標準化 |
API Documentation Best Practices
概要
OpenAPI、Swagger、RESTful APIドキュメンテーションのベストプラクティスを提供する専門スキル。
詳細な手順や背景は references/Level1_basics.md と references/Level2_intermediate.md を参照してください。
ワークフロー
Phase 1: 目的と前提の整理
目的: タスクの目的と前提条件を明確にする
アクション:
references/Level1_basics.mdとreferences/Level2_intermediate.mdを確認- 必要な references/scripts/templates を特定
Task: agents/analyze-documentation-context.md を参照
Phase 2: スキル適用
目的: スキルの指針に従って具体的な作業を進める
アクション:
- 関連リソースやテンプレートを参照しながら作業を実施
- 重要な判断点をメモとして残す
Task: agents/create-documentation.md を参照
Phase 3: 検証と記録
目的: 成果物の検証と実行記録の保存
アクション:
scripts/validate-skill.mjsでスキル構造を確認- 成果物が目的に合致するか確認
scripts/log_usage.mjsを実行して記録を残す
Task: agents/validate-documentation.md を参照
Task仕様ナビ
| 種類 | 説明 | リソース | テンプレート |
|---|---|---|---|
| 基礎知識 | OpenAPIドキュメンテーションの基本概念と設計パターン | references/Level1_basics.md |
- |
| 実装ガイド | RESTful API仕様書作成の実務テクニック | references/Level2_intermediate.md |
assets/endpoint-template.md |
| 応用手法 | 複雑なAPI設計と高度なドキュメンテーション | references/Level3_advanced.md |
- |
| 専門知識 | API設計のエキスパートレベルの考察 | references/Level4_expert.md |
- |
| 認証設計 | OAuth2、JWT等の認証フロー文書化 | references/authentication-docs.md |
- |
| エンドポイント設計 | リソース設計とHTTP操作の標準化 | references/endpoint-design.md |
assets/endpoint-template.md |
| エラー定義 | エラーレスポンスとステータスコード管理 | references/error-documentation.md |
- |
| OpenAPI詳細 | OpenAPI 3.x仕様の詳細ガイド | references/openapi-guide.md |
assets/openapi-template.yaml |
| リクエスト/レスポンス例 | 実践的な例とサンプルコード | references/request-response-examples.md |
- |
| 要求仕様索引 | 要求仕様書との同期状態確認 | references/requirements-index.md |
- |
ベストプラクティス
すべきこと
- REST APIの仕様書を作成する時は、リソース指向の設計原則に従う
- OpenAPI/Swagger定義を設計する時は、
references/openapi-guide.mdの標準フォーマットを参照する - APIエンドポイントの詳細仕様を文書化する時は、
assets/endpoint-template.mdを使用する - 認証フローを説明する時は、
references/authentication-docs.mdで推奨パターンを確認する - エラーレスポンスを定義する時は、統一されたステータスコードとエラー構造を使用する
- リクエスト/レスポンス例は実際の運用ケースに基づいて作成する
- ドキュメントはバージョン管理対象とし、API変更時に同期を保つ
避けるべきこと
- アンチパターンや注意点を確認せずに進めることを避ける
- 認証仕様を不完全なまま進める(セキュリティリスク)
- エラー定義を曖昧にして、クライアント側の実装を困難にする
- OpenAPI仕様を部分的にしか定義しない(生成ツールやSDK生成が失敗する)
- レガシーな仕様書を放置する(古い情報が蔓延する)
- サンプルコードを更新しないまま放置する(実装と乖離する)
- HTTP操作の語義(GET/POST等)を無視した設計をする
リソース参照
📚 学習リソース
| レベル | 説明 | ファイル |
|---|---|---|
| レベル1: 基礎 | 基本的な概念と用語 | references/Level1_basics.md |
| レベル2: 実務 | 実装に必要な知識 | references/Level2_intermediate.md |
| レベル3: 応用 | 応用的な手法と最適化 | references/Level3_advanced.md |
| レベル4: 専門 | エキスパート向けの考察 | references/Level4_expert.md |
🔧 スクリプトツール
# OpenAPI仕様のバリデーション
node .claude/skills/api-documentation-best-practices/scripts/validate-openapi.mjs <openapi-file>
# スキル構造の検証
node .claude/skills/api-documentation-best-practices/scripts/validate-skill.mjs
# 使用記録と自動評価
node .claude/skills/api-documentation-best-practices/scripts/log_usage.mjs --help
📋 テンプレート
assets/endpoint-template.md- エンドポイント仕様書テンプレートassets/openapi-template.yaml- OpenAPI 3.0.3定義テンプレート
📖 参考書籍
- 『RESTful Web APIs』(Leonard Richardson著)
- リソース設計の原則
- HTTP操作の正しい使い方
- ステートレス設計のベストプラクティス
変更履歴
| Version | Date | Changes |
|---|---|---|
| 3.0.0 | 2025-12-31 | agents/3ファイル追加、Phase別Task参照を追加、name修正 |
| 2.0.0 | 2025-12-31 | 18-skills.md仕様へ完全移行: YAML frontmatter (Anchors/Triggers/allowed-tools)、Task仕様ナビテーブル、リソース参照セクション拡充 |
| 1.0.0 | 2025-12-24 | Spec alignment and required artifacts added |