mcpField
A
api-documenter

api-documenter

github.com/404kidwiz開発99 回インストール
リポジトリ

api-documenter について

API Documenter は、正確で読みやすい API ドキュメントを作成する開発者向けのスキルです。OpenAPI 仕様、GraphQL スキーマ、インタラクティブなリファレンス、入門ガイドを扱います。

主な機能

  1. 01OpenAPI 仕様の作成
  2. 02REST エンドポイントのリファレンス
  3. 03GraphQL スキーマのドキュメント
  4. 04インタラクティブ API リファレンスの設計
  5. 05API 入門ガイドの作成

活用シーン

  1. 01REST API とエラーの文書化
  2. 02GraphQL スキーマガイドの作成
  3. 03API 認証手順の案内作成
  4. 04SDK 使用例の準備

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/404kidwiz/claude-supercode-skills --skill api-documenter

インストール後、Claude Code で/api-documenterを入力して読み込まれたか確認します。

詳細

API ドキュメンター

目的

明確で正確、かつ開発者にとって使いやすい API ドキュメントの作成に関する専門知識を提供します。OpenAPI 3.x 仕様、GraphQL スキーマのドキュメント、インタラクティブな API リファレンスを専門としています。

使用する場面

  • OpenAPI/Swagger 仕様の作成
  • REST API エンドポイントのドキュメント作成
  • GraphQL スキーマのドキュメント作成
  • インタラクティブな API リファレンスの構築
  • API の入門ガイドの作成
  • 認証フローのドキュメント作成
  • SDK の使用例の作成

クイックスタート

このスキルを呼び出す場面：

  • OpenAPI/Swagger 仕様の作成
  • REST API エンドポイントのドキュメント作成
  • GraphQL スキーマのドキュメント作成
  • インタラクティブな API リファレンスの構築
  • SDK の使用例の作成

呼び出さない場面：

  • API アーキテクチャの設計（api-designer を使用）
  • ユーザー向け製品ドキュメントの作成（technical-writer を使用）
  • 社内システムドキュメントの作成（document-writer を使用）
  • 実際の API の構築（バックエンド開発者向けスキルを使用）

判断フレームワーク

Documentation Type:
├── New API → OpenAPI spec first, then guides
├── Existing API → Audit endpoints, generate spec
├── GraphQL → Schema docs + query examples
├── SDK/Library → Code samples + quickstart
└── Microservices → Service catalog + contracts

主なワークフロー

1. OpenAPI 仕様の作成
  1. すべてのエンドポイントとメソッドを洗い出します
  2. リクエスト／レスポンスのスキーマを定義します
  3. パラメーターとヘッダーを記載します
  4. 認証要件を追加します
  5. リクエスト／レスポンスの例を含めます
  6. リンティングツールで仕様を検証します
2. API リファレンスのドキュメント作成
  1. エンドポイントをリソースまたはドメインごとに分類します
  2. エンドポイントを明確に説明します
  3. すべてのパラメーターを型とともに記載します
  4. リクエスト／レスポンスの例を示します
  5. エラーコードとその処理方法を含めます
  6. 認証の例を追加します
3. API 入門ガイド
  1. 認証の設定方法を説明します
  2. 最初の API 呼び出しの例を示します
  3. 一般的なユースケースを順を追って説明します
  4. SDK のインストール手順を含めます
  5. トラブルシューティングのヒントを示します
  6. リファレンスドキュメント全体へのリンクを掲載します

ベストプラクティス

  • すべてのドキュメントで用語を統一します
  • コピーしてすぐに使えるコード例を提供します
  • 成功時とエラー時の両方のレスポンスを含めます
  • API のバージョンに合わせてドキュメントをバージョン管理します
  • 公開前にすべてのコード例をテストします
  • レート制限とクォータの情報を追加します

アンチパターン

アンチパターン問題点適切な対応
例がない開発者が使い方を推測することになりますリクエスト／レスポンスの例を含めます
ドキュメントが古い開発者の信頼を損ないますコードからのドキュメント生成を自動化します
エラーの記載がない本番環境で予期しない障害が発生しますすべてのエラーコードを記載します
専門用語が多すぎる開発を始めたばかりの人を混乱させます明確で簡潔な言葉を使います
バージョン管理がない破壊的変更が不明確になりますAPI に合わせてドキュメントをバージョン管理します

コメント

Markdown 対応