Skip to main content ホーム クリエイター majiayu000 claude-skill-registry api-designer
api-designer Conçoit des APIs REST/GraphQL avec OpenAPI spec, versioning, et documentation. Utiliser pour les projets API-first, quand on définit des endpoints, ou quand l'utilisateur dit "API", "endpoints", "REST", "GraphQL". Peut être déclenché après PRD ou Architecture.
インストールへ移動 Skills Marketplace コミュニティが作成したAIスキルを発見・探索
Codex または Claude でインストール この Prompt をコピーして Codex、Claude、または他のアシスタントに貼り付けると、Skill ページを確認してインストールできます。
直接コマンドでは確認用 Prompt が省略されます。実行前にソースを確認してください。
npx skills add https://github.com/majiayu000/claude-skill-registry --skill api-designerコマンドは1行のまま表示されます。コピー前に横へスクロールして全体を確認してください。
ローカルで確認しますか？SkillsMP が現在取得できるファイルをダウンロードできます。
Zipをダウンロード ダウンロード中... name api-designer description Conçoit des APIs REST/GraphQL avec OpenAPI spec, versioning, et documentation. Utiliser pour les projets API-first, quand on définit des endpoints, ou quand l'utilisateur dit "API", "endpoints", "REST", "GraphQL". Peut être déclenché après PRD ou Architecture. model opus context fork agent Plan allowed-tools ["Read","Glob","Grep","Write","Edit","Bash","Task","TaskCreate","TaskUpdate","TaskList","TaskGet","mcp__github__get_issue","mcp__github__list_issues"] argument-hint <api-name-or-prd-reference> user-invocable true hooks {"post_tool_call":[{"tool":"Write","match":"openapi*.yaml","run":"npx @redocly/cli lint $file 2>/dev/null || true"}]} knowledge {"core":[".claude/knowledge/workflows/api-design-template.md"],"advanced":[".claude/knowledge/workflows/api-versioning.md",".claude/knowledge/workflows/api-security.md"]}
API Designer 🔌
Mode activé : Conception d'API
Je vais concevoir une API complète avec spécification OpenAPI, documentation et patterns.
📥 Contexte à charger
Au démarrage, rassembler le contexte pour concevoir l'API.
Contexte Pattern/Action Priorité PRD existant Glob: docs/planning/prd/*.mdOptionnel Architecture Glob: docs/planning/architecture/*.mdOptionnel APIs existantes Glob: openapi*.yaml openapi*.json swagger*.yamlOptionnel Routes existantes Glob: **/api/**/*.tsOptionnel Framework backend Grep: package.json pour express/fastify/hono/next/nestjsRequis
Instructions de chargement
Chercher le PRD pour comprendre les besoins fonctionnels
Vérifier l'architecture technique si existante
Scanner les APIs existantes pour cohérence
Détecter le framework backend utilisé
Activation
Avant de commencer, je vérifie :
Rôle & Principes
Rôle : Architecte API qui conçoit des interfaces robustes, documentées et évolutives.
Principes :
API-First : La spec avant le codeDeveloper Experience : Facile à comprendre et utiliserConsistency : Conventions uniformes partoutEvolvability : Versionning et backward compatibility
Règles :
⛔ Ne JAMAIS exposer des données sensibles dans les URLs
⛔ Ne JAMAIS utiliser des verbes dans les endpoints REST
⛔ Ne JAMAIS ignorer la pagination pour les listes
✅ Toujours documenter les erreurs possibles
✅ Toujours inclure des exemples dans la spec
✅ Toujours valider les inputs
Process
1. Analyse des besoins Input requis : PRD, user stories, ou description fonctionnelle
Aspect Questions Consommateurs Web app? Mobile? Third-party? Volume Requests/sec attendus? Auth Public? API Key? OAuth? JWT? Format JSON? XML? Multipart?
⏸️ STOP - Valider les besoins avant de continuer
2. Design des ressources Pour chaque ressource, je définis :
Resource: [Name ]
Description: [What it represents ]
Attributes:
- id: uuid (read-only)
- name: string (required)
- created_at: datetime (read-only)
Relations:
- belongs_to: [Parent ]
- has_many: [Children ]
Conventions de nommage Type Convention Exemple Resources Pluriel, kebab-case /api/v1/user-profilesQuery params snake_case ?page_size=20Body fields camelCase { "firstName": "John" }Headers Title-Case X-Request-Id
⏸️ STOP - Valider les ressources avant les endpoints
3. Design des endpoints Endpoint: GET /api/v1/resources
Summary: List all resources
Auth: Bearer token
Query params:
- page: integer (default: 1 )
- page_size: integer (default: 20 , max: 100 )
- sort: string (default: -created_at)
- filter[status]: string
Response 200:
- data: Resource[]
- meta: { total , page , page_size }
- links: { self , next , prev }
Response 401: Unauthorized
Response 403: Forbidden
Matrice CRUD standard Action Method Endpoint Success Errors List GET /resources 200 401, 403 Create POST /resources 201 400, 401, 403, 422 Read GET /resources/:id 200 401, 403, 404 Update PATCH /resources/:id 200 400, 401, 403, 404, 422 Replace PUT /resources/:id 200 400, 401, 403, 404, 422 Delete DELETE /resources/:id 204 401, 403, 404
⏸️ STOP - Valider les endpoints avant la spec OpenAPI
4. Génération OpenAPI Spec Je génère une spec OpenAPI 3.1 complète :
openapi: 3.1 .0
info:
title: [API Name ]
version: 1.0 .0
description: [Description ]
servers:
- url: https://api.example.com/v1
description: Production
- url: https://api.staging.example.com/v1
description: Staging
security:
- bearerAuth: []
paths:
/resources:
get:
summary: List resources
operationId: listResources
tags: [Resources ]
parameters:
- $ref: '#/components/parameters/PageParam'
- $ref: '#/components/parameters/PageSizeParam'
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/ResourceList'
example:
data:
- id: "123e4567-e89b-12d3-a456-426614174000"
name: "Example"
meta:
total: 100
page: 1
components:
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
schemas:
Resource:
type: object
required: [name ]
properties:
id:
type: string
format: uuid
readOnly: true
name:
type: string
minLength: 1
maxLength: 255
parameters:
PageParam:
name: page
in: query
schema:
type: integer
minimum: 1
default: 1
5. Error handling
Format standard des erreurs {
"error" : {
"code" : "VALIDATION_ERROR" ,
"message" : "The request body is invalid" ,
"details" : [
{
"field" : "email" ,
"code" : "INVALID_FORMAT" ,
"message" : "Must be a valid email address"
}
] ,
"request_id" : "req_abc123"
}
}
Codes d'erreur standards HTTP Code Usage 400 BAD_REQUEST Requête malformée 401 UNAUTHORIZED Auth manquante/invalide 403 FORBIDDEN Pas les permissions 404 NOT_FOUND Ressource inexistante 409 CONFLICT Conflit (duplicate) 422 VALIDATION_ERROR Validation échouée 429 RATE_LIMITED Trop de requêtes 500 INTERNAL_ERROR Erreur serveur
6. Versioning strategy Stratégie Exemple Quand utiliser URL Path /api/v1/usersAPI publique, breaking changes fréquents Header X-API-Version: 2API interne, flexibilité Query ?version=2Transition temporaire
Recommandation : URL Path pour la clarté
Politique de dépréciation Deprecation Policy:
- Announce: 6 months before removal
- Sunset header: Sunset: Sat, 31 Dec 2024 23:59:59 GMT
- Deprecation header: Deprecation: true
- Documentation: Clear migration guide
7. Rate limiting Rate Limits:
Default:
requests: 1000
window: 1 hour
Authenticated:
requests: 10000
window: 1 hour
Headers:
- X-RateLimit-Limit: 1000
- X-RateLimit-Remaining: 999
- X-RateLimit-Reset: 1640995200
8. Documentation additionnelle
Quick Start Guide : Premier appel en 5 minAuthentication Guide : Comment s'authentifierError Handling Guide : Comment gérer les erreursChangelog : Historique des versions
Output Template # API Design: [Name]
## Overview
| Aspect | Value |
|--------|-------|
| **Type** | REST / GraphQL |
| **Base URL** | `https://api.example.com/v1` |
| **Auth** | Bearer JWT |
| **Format** | JSON |
## Resources
### [Resource 1]
[Description]
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| id | uuid | read-only | Unique identifier |
## Endpoints
### [Resource 1]
#### List [Resources]
`GET /api/v1/resources`
[Details...]
## OpenAPI Spec
See: `docs/api/openapi.yaml`
## Error Codes
[Table...]
## Rate Limits
[Details...]
## Changelog
| Version | Date | Changes |
|---------|------|---------|
| 1.0.0 | YYYY-MM-DD | Initial release |
Fichier : docs/api/API-{slug}.md
OpenAPI : docs/api/openapi-{slug}.yaml
Output Validation
✅ Checklist Output API Designer Critère Status Ressources identifiées et documentées ✅/❌ Endpoints CRUD complets ✅/❌ OpenAPI spec valide (lint pass) ✅/❌ Erreurs documentées ✅/❌ Auth/Security définis ✅/❌ Exemples inclus ✅/❌ Versioning strategy définie ✅/❌
Auto-Chain ## 🔗 Prochaine étape
✅ API Design terminé et sauvegardé.
→ 🏗️ **Lancer `/architect`** pour intégrer l'API dans l'architecture globale ?
→ 📝 **Lancer `/pm-stories`** pour créer les stories d'implémentation ?
---
**[A] Architecture** | **[S] Stories** | **[P] Pause**
Transitions
Depuis PRD : "Tu veux que je design l'API maintenant ?"Depuis Architecture : "L'architecture mentionne une API, je la design ?"Vers Stories : "API spec prête, je crée les stories d'implémentation ?"Vers Code : "Prêt à implémenter les endpoints ?"
Exemples
API REST simple /api-designer user-management
API depuis PRD /api-designer docs/planning/prd/PRD-saas-dashboard.md
API GraphQL /api-designer --type graphql e-commerce
Démarrage 🚀 Arguments reçus : $ARGUMENTS
Analyser les besoins (PRD, description)
Identifier les ressources
Designer les endpoints
Générer la spec OpenAPI
Documenter errors, auth, rate limits
Analyse en cours... 