mcpField
A
api-documenter

api-documenter

github.com/zhaono1開発85718 回インストール9 週間前に更新
リポジトリ

api-documenter について

OpenAPI/Swagger仕様に基づくAPIリファレンス作成を支援するスキルです。エンドポイント、スキーマ、認証、エラーの記述に加え、仕様の生成と検証も案内します。

主な機能

  1. 01OpenAPIエンドポイントの文書化
  2. 02スキーマとプロパティの記述指針
  3. 03認証とエラーの文書化
  4. 04仕様の生成・検証の案内

活用シーン

  1. 01APIリファレンスの作成
  2. 02エンドポイントのパラメーターと応答の記録
  3. 03スキーマと認証要件の説明
  4. 04OpenAPI仕様の生成や確認

インストール

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

$npx skills add https://github.com/zhaono1/agent-playbook --skill api-documenter

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

同梱ファイル

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

README.md
references/
openapi-template.yaml
references/examples/
openapi-example.yaml
README.md
scripts/
generate_openapi.py
validate_openapi.py

詳細

API ドキュメント作成者

OpenAPI/Swagger 仕様を使用した、包括的な API ドキュメントの作成を専門とします。

このスキルが有効になる場合

次のような場合に有効になります。

  • API のドキュメント作成を依頼する
  • OpenAPI/Swagger 仕様を作成する
  • API リファレンスドキュメントが必要になる
  • 「API ドキュメント」と言及する

OpenAPI 仕様の構造

openapi: 3.0.3
info:
  title: API Title
  version: 1.0.0
  description: API description
servers:
  - url: https://example.com/api/v1
paths:
  /users:
    get:
      summary: List users
      operationId: listUsers
      tags:
        - users
      parameters: []
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'
components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: string
        name:
          type: string

エンドポイントのドキュメント

各エンドポイントについて、次の内容を記述します。

必須フィールド
  • summary：簡潔な説明
  • operationId：一意の識別子
  • description：詳しい説明
  • tags：グループ分け用
  • responses：考えられるすべてのレスポンス
推奨フィールド
  • parameters：詳細を含むすべてのパラメーター
  • requestBody：POST/PUT/PATCH 用
  • security：認証要件
  • deprecated：該当する場合
例
/users/{id}:
  get:
    summary: Get a user by ID
    operationId: getUserById
    description: Retrieves a single user by their unique identifier
    tags:
      - users
    parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
        description: The user ID
    responses:
      '200':
        description: User found
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/User'
      '404':
        description: User not found
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Error'

スキーマのドキュメント

ベストプラクティス
  1. 共有スキーマには参照を使用する
  2. すべてのプロパティに説明を追加する
  3. 文字列の形式を指定する（email、uuid、date-time）
  4. 複雑なスキーマには例を追加する
  5. 必須フィールドに印を付ける
例
components:
  schemas:
    User:
      type: object
      required:
        - id
        - email
      properties:
        id:
          type: string
          format: uuid
          description: Unique user identifier
          example: "550e8400-e29b-41d4-a716-446655440000"
        email:
          type: string
          format: email
          description: User's email address
          example: "[email protected]"
        createdAt:
          type: string
          format: date-time
          description: Account creation timestamp

認証のドキュメント

認証要件を記述します。

security:
  - bearerAuth: []

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Use your JWT token from /auth/login

エラーレスポンス

標準的なエラー形式：

components:
  schemas:
    Error:
      type: object
      properties:
        error:
          type: string
          description: Error message
        code:
          type: string
          description: Application-specific error code
        details:
          type: object
          description: Additional error details

一般的な HTTP ステータスコード：

  • 200：成功
  • 201：作成済み
  • 204：コンテンツなし
  • 400：不正なリクエスト
  • 401：認証されていません
  • 403：アクセス禁止
  • 404：見つかりません
  • 409：競合
  • 422：処理できないエンティティ
  • 500：内部サーバーエラー

スクリプト

コードから OpenAPI 仕様を生成します：

python3 scripts/generate_openapi.py --name <resource-name> --output openapi.yaml

OpenAPI 仕様を検証します：

python3 scripts/validate_openapi.py --input openapi.yaml

参考資料

  • references/openapi-template.yaml - OpenAPI テンプレート
  • references/examples/ - API ドキュメントの例
  • OpenAPI 仕様

コメント

Markdown 対応