mcpField
A
api-reference-documentation

api-reference-documentation

github.com/secondsky開発240460 回インストール5 週間前に更新
リポジトリ

api-reference-documentation について

OpenAPI仕様、エンドポイントの詳細、例、保守方法を扱うAPIリファレンス作成スキルです。連携用APIを文書化する開発者向けです。

主な機能

  1. 01OpenAPI 3.0仕様の指針
  2. 02エンドポイントとパラメーターの確認項目
  3. 03リクエストとレスポンスの例
  4. 04認証とエラーの記述
  5. 05バージョン管理と移行の指針
  6. 06インタラクティブな探索ツールの候補

活用シーン

  1. 01開発者連携向けAPI文書の作成
  2. 02エンドポイント資料の網羅性確認
  3. 03認証方式とエラーレスポンスの説明
  4. 04互換性を損なう変更の文書準備

インストール

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

$npx skills add https://github.com/secondsky/claude-skills --skill api-reference-documentation

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

詳細

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

開発者向け統合のための包括的な API ドキュメントを作成します。

OpenAPI 3.0 仕様

openapi: 3.0.3
info:
  title: E-Commerce API
  version: 1.0.0
  description: API for managing products and orders
  contact:
    email: [email protected]

servers:
  - url: https://api.example.com/v1
    description: Production
  - url: https://staging-api.example.com/v1
    description: Staging

security:
  - bearerAuth: []

paths:
  /products:
    get:
      summary: List products
      tags: [Products]
      parameters:
        - name: limit
          in: query
          schema: { type: integer, default: 20 }
        - name: category
          in: query
          schema: { type: string }
      responses:
        '200':
          description: Product list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProductList'

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

  schemas:
    Product:
      type: object
      required: [id, name, price]
      properties:
        id: { type: string, format: uuid }
        name: { type: string, maxLength: 200 }
        price: { type: number, minimum: 0 }
        description: { type: string }

ドキュメント作成チェックリスト

  • すべてのエンドポイントを例とともに記載する
  • 認証方法を説明する
  • エラーレスポンスを明記する
  • レート制限を記載する
  • ページネーションを説明する
  • Webhook を記載する（該当する場合）
  • 複数の言語で SDK の例を示す

ベストプラクティス

  • OpenAPI 3.0 以降の仕様を使用する
  • リクエストとレスポンスの例を含める
  • すべてのパラメーターとヘッダーを記載する
  • 認証の例を示す
  • インタラクティブな API の確認を可能にする
  • バージョンごとのドキュメントを維持する
  • 互換性を損なう変更に関する移行ガイドを含める

ツール

  • Swagger Editor / Swagger UI
  • Redoc
  • Postman Documentation
  • Stoplight

コメント

Markdown 対応