mcpField
A
api-reference-documentation

api-reference-documentation

github.com/aj-geddes開発373496 回インストール34 週間前に更新
リポジトリ

api-reference-documentation について

開発者向けのAPIリファレンスを作成するスキルです。エンドポイント、認証、リクエストとレスポンスの例、対話型ドキュメントを扱い、REST、GraphQL、OpenAPI、SDKなどを案内します。

主な機能

  1. 01OpenAPI仕様のガイダンス
  2. 02エンドポイントとパラメーターの文書化
  3. 03認証とエラーの例
  4. 04SDKとクライアントライブラリの文書
  5. 05Webhookとバージョン管理のガイド

活用シーン

  1. 01REST APIの文書作成
  2. 02GraphQL APIリファレンスの作成
  3. 03認証とレート制限ガイドの準備
  4. 04WebhookとAPIバージョンの記録

インストール

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

$npx skills add https://github.com/aj-geddes/useful-ai-prompts --skill api-reference-documentation

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

同梱ファイル

SKILL.md と一緒にインストールされる参考資料やスクリプト。

references/
list-products.md
openapi-specification-example.md
scripts/
validate-api.sh
templates/
api-scaffold.yaml

詳細

API リファレンスドキュメント

目次

概要

開発者が API と連携する際に利用できる、エンドポイントの仕様、認証、リクエスト／レスポンスの例、インタラクティブなドキュメントを含む、専門的な API ドキュメントを生成します。

使用する場面

  • REST API のドキュメント作成
  • OpenAPI/Swagger 仕様の作成
  • GraphQL API のドキュメント作成
  • SDK とクライアントライブラリのドキュメント
  • API 認証ガイド
  • レート制限のドキュメント
  • Webhook のドキュメント
  • API バージョン管理ガイド

クイックスタート

最小限の実行例：

openapi: 3.0.3
info:
  title: E-Commerce API
  description: |
    Complete API for managing e-commerce operations including products,
    orders, customers, and payments.

    ## Authentication
    All endpoints require Bearer token authentication. Include your API key
    in the Authorization header: `Authorization: Bearer YOUR_API_KEY`

    ## Rate Limiting
    - 1000 requests per hour for authenticated users
    - 100 requests per hour for unauthenticated requests

    ## Pagination
    List endpoints return paginated results with `page` and `limit` parameters.
  version: 2.0.0
  contact:
    name: API Support
    email: [email protected]
    url: https://example.com/support
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT
// ... (see reference guides for full implementation)

リファレンスガイド

詳細な実装については、references/ ディレクトリを参照してください。

ガイド内容
OpenAPI 仕様の例openapi: 3.0.3
製品一覧製品一覧

ベストプラクティス

✅ 推奨事項
  • OpenAPI 3.0 以降の仕様を使用する
  • すべてのエンドポイントにリクエスト／レスポンスの例を含める
  • すべてのクエリパラメーターとヘッダーをドキュメント化する
  • 認証の例を示す
  • エラーレスポンスの形式を含める
  • レート制限とページネーションをドキュメント化する
  • 一貫した命名規則を使用する
  • 複数の言語による SDK の例を含める
  • Webhook のペイロードをドキュメント化する
  • インタラクティブな API エクスプローラー（Swagger UI）を提供する
  • API ドキュメントをバージョン管理する
  • 互換性を損なう変更に関する移行ガイドを含める
❌ 避ける事項
  • エラーレスポンスのドキュメントを省略する
  • 認証のドキュメントを忘れる
  • 一貫性のない用語を使用する
  • エンドポイントのドキュメントを作成しないままにする
  • 非推奨の通知を無視する
  • バージョン情報を省略する

コメント

Markdown 対応