mcpField
A
api-docs

api-docs

github.com/langchain-ai開発11960 回インストール11 週間前に更新
リポジトリ

api-docs について

api-docsは、RESTful APIを設計・文書化する開発者向けのスキルです。OpenAPI 3.0+、RESTの規約、構造化されたエラーレスポンスを扱います。

主な機能

  1. 01OpenAPI 3.0+への準拠
  2. 02RESTリソースの命名規約
  3. 03HTTPメソッドとステータスコード
  4. 04ページネーションとAPIバージョン
  5. 05構造化エラーレスポンス

活用シーン

  1. 01REST APIの仕様書作成
  2. 02メソッドとステータスコードの標準化
  3. 03一覧エンドポイントのページネーション設計

インストール

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

$npx skills add https://github.com/langchain-ai/skills-benchmarks --skill api-docs

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

詳細

API ドキュメントの標準

業界標準に従って RESTful API を設計し、ドキュメントを作成します。

OpenAPI 仕様

API は必ず OpenAPI 3.0 以降を使用してドキュメント化します。

openapi: 3.0.3
info:
  title: User API
  version: 1.0.0

paths:
  /users:
    get:
      summary: List users
      parameters:
        - name: limit
          in: query
          schema:
            type: integer
            default: 20
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'

components:
  schemas:
    User:
      type: object
      required: [id, email]
      properties:
        id:
          type: string
          format: uuid
        email:
          type: string
          format: email

REST の規約

  1. リソースには名詞を使用します：/users、/orders
  2. HTTP メソッドを正しく使用します：GET、POST、PUT、PATCH、DELETE
  3. 適切なステータスコードを返します：200、201、400、404、500
  4. リストにはページネーションを使用します：?page=1&limit=20
  5. API のバージョンを指定します：/v1/users

エラーレスポンス

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid input",
    "details": [
      {"field": "email", "message": "Invalid email format"}
    ]
  }
}

コメント

Markdown 対応