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: api@example.com
    url: https://example.com/support
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT
// ... (see reference guides for full implementation)

リファレンスガイド

references/ ディレクトリの詳細な実装：

ベストプラクティス

✅ 推奨事項

• OpenAPI 3.0+ 仕様を使用する
• すべてのエンドポイントにリクエスト/レスポンス例を含める
• すべてのクエリパラメータとヘッダーをドキュメント化する
• 認証例を提供する
• エラーレスポンス形式をドキュメント化する
• レート制限とページネーションをドキュメント化する
• 一貫性のある命名規則を使用する
• 複数の言語で SDK 例を含める
• Webhook ペイロードをドキュメント化する
• インタラクティブ API エクスプローラ (Swagger UI) を提供する
• API ドキュメントをバージョン管理する
• 破壊的変更に対する移行ガイドを含める

❌ 非推奨事項

• エラーレスポンスドキュメントをスキップする
• 認証のドキュメント化を忘れる
• 用語の使い方に一貫性がない
• エンドポイントをドキュメント化しない
• 非推奨通知を無視する
• バージョン情報をスキップする