api
npx machina-cli add skill AI-Driven-School/aiki/api --openclawFiles (1)
SKILL.md
3.9 KB
/api スキル
エンドポイント名からOpenAPI仕様書を生成します。
使用方法
/api auth
/api users
/api products
出力テンプレート
docs/api/{endpoint}.yaml に出力:
openapi: 3.0.0
info:
title: {機能名} API
version: 1.0.0
description: {APIの概要}
servers:
- url: /api/v1
description: API v1
paths:
/{endpoint}:
get:
summary: {概要}
description: {詳細説明}
tags:
- {タグ}
parameters:
- name: {パラメータ名}
in: query
required: false
schema:
type: string
description: {説明}
responses:
'200':
description: 成功
content:
application/json:
schema:
$ref: '#/components/schemas/{Schema名}'
'401':
description: 認証エラー
'500':
description: サーバーエラー
post:
summary: {概要}
description: {詳細説明}
tags:
- {タグ}
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/{Request Schema}'
responses:
'201':
description: 作成成功
content:
application/json:
schema:
$ref: '#/components/schemas/{Response Schema}'
'400':
description: バリデーションエラー
'401':
description: 認証エラー
components:
schemas:
{Schema名}:
type: object
required:
- {必須フィールド}
properties:
id:
type: string
format: uuid
description: 一意識別子
{フィールド名}:
type: {型}
description: {説明}
createdAt:
type: string
format: date-time
description: 作成日時
updatedAt:
type: string
format: date-time
description: 更新日時
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
security:
- bearerAuth: []
生成ガイドライン
- RESTful原則: リソース指向のエンドポイント設計
- 一貫性: 命名規則、レスポンス形式を統一
- エラーハンドリング: 標準的なHTTPステータスコード使用
- セキュリティ: 認証が必要なエンドポイントを明記
出力例
> /api auth
📋 API設計を生成中... (Claude)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📄 docs/api/auth.yaml を作成しました
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
openapi: 3.0.0
info:
title: 認証 API
version: 1.0.0
paths:
/auth/login:
post:
summary: ログイン
requestBody:
content:
application/json:
schema:
type: object
required: [email, password]
properties:
email:
type: string
format: email
password:
type: string
minLength: 8
responses:
'200':
description: ログイン成功
content:
application/json:
schema:
type: object
properties:
token:
type: string
user:
$ref: '#/components/schemas/User'
...
承認しますか？ [Y/n/reject 理由]
Source
git clone https://github.com/AI-Driven-School/aiki/blob/main/.claude/skills/api/SKILL.mdView on GitHub Overview
Generates OpenAPI 3.0 specification documents from endpoint names. This skill helps you design REST APIs and create API docs efficiently. Outputs are placed under docs/api/{endpoint}.yaml and include endpoints, schemas, and a bearerAuth security definition.
How This Skill Works
Provide an endpoint name (e.g., auth, users, products); the tool builds an OpenAPI 3.0 skeleton with paths, methods, and request/response schemas. It references schemas via $ref and includes a bearerAuth security scheme, then writes the YAML to docs/api/{endpoint}.yaml.
When to Use It
- Design a new REST API by generating an OpenAPI file from an endpoint name (e.g., /api auth -> auth.yaml).
- Create comprehensive API docs quickly by exporting endpoint specifications to docs/api/{endpoint}.yaml.
- Standardize request/response schemas and security definitions across endpoints.
- Define and preview security with bearer JWT in the generated spec.
- Produce a reusable API spec skeleton to share with a team before implementation.
Quick Start
- Step 1: Run the skill with an endpoint name, e.g., /api auth, /api users, or /api products.
- Step 2: Check the generated file at docs/api/{endpoint}.yaml.
- Step 3: Validate the OpenAPI spec and integrate it into your API docs workflow.
Best Practices
- Follow RESTful resource naming for endpoints.
- Keep consistent paths, tags, and response formats across endpoints.
- Use standard HTTP status codes (200/201/400/401/500) in responses.
- Define bearerAuth for endpoints requiring authentication and document security usage.
- Leverage $ref references to reuse schemas and avoid duplication in components/schemas.
Example Use Cases
- Generate /api auth to build an authentication API spec.
- Generate /api users for a user management API.
- Generate /api products for a product catalog API.
- Include securitySchemes: bearerAuth and document a login flow.
- Output docs/api/auth.yaml and validate with an OpenAPI validator.
Frequently Asked Questions
Add this skill to your agents
