API Documentation Best Practices

API Documentation Best Practices

概要

OpenAPI、Swagger、RESTful APIドキュメンテーションのベストプラクティスを提供する専門スキル。

詳細な手順や背景は references/Level1_basics.md と references/Level2_intermediate.md を参照してください。

ワークフロー

Phase 1: 目的と前提の整理

目的: タスクの目的と前提条件を明確にする

アクション:

1. references/Level1_basics.md と references/Level2_intermediate.md を確認
2. 必要な references/scripts/templates を特定

Task: agents/analyze-documentation-context.md を参照

Phase 2: スキル適用

目的: スキルの指針に従って具体的な作業を進める

アクション:

1. 関連リソースやテンプレートを参照しながら作業を実施
2. 重要な判断点をメモとして残す

Task: agents/create-documentation.md を参照

Phase 3: 検証と記録

目的: 成果物の検証と実行記録の保存

アクション:

1. scripts/validate-skill.mjs でスキル構造を確認
2. 成果物が目的に合致するか確認
3. scripts/log_usage.mjs を実行して記録を残す

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

Task仕様ナビ

ベストプラクティス

すべきこと

• REST APIの仕様書を作成する時は、リソース指向の設計原則に従う
• OpenAPI/Swagger定義を設計する時は、references/openapi-guide.md の標準フォーマットを参照する
• APIエンドポイントの詳細仕様を文書化する時は、assets/endpoint-template.md を使用する
• 認証フローを説明する時は、references/authentication-docs.md で推奨パターンを確認する
• エラーレスポンスを定義する時は、統一されたステータスコードとエラー構造を使用する
• リクエスト/レスポンス例は実際の運用ケースに基づいて作成する
• ドキュメントはバージョン管理対象とし、API変更時に同期を保つ

避けるべきこと

• アンチパターンや注意点を確認せずに進めることを避ける
• 認証仕様を不完全なまま進める（セキュリティリスク）
• エラー定義を曖昧にして、クライアント側の実装を困難にする
• OpenAPI仕様を部分的にしか定義しない（生成ツールやSDK生成が失敗する）
• レガシーな仕様書を放置する（古い情報が蔓延する）
• サンプルコードを更新しないまま放置する（実装と乖離する）
• HTTP操作の語義（GET/POST等）を無視した設計をする

リソース参照

📚 学習リソース

🔧 スクリプトツール

# 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操作の正しい使い方
  • ステートレス設計のベストプラクティス

変更履歴