openapi-spec-generation
إنشاء مواصفات OpenAPI 3.1
إنشاء وصيانة وثائق API يستغرق وقتًا طويلًا وعرضة للأخطاء. توفر هذه المهارة قوالب شاملة وأمثلة كود وأنماط التحقق من صحة مواصفات OpenAPI 3.1 لتبسيط سير عمل توثيق API.
Télécharger le ZIP du skill
Importer dans Claude
Allez dans Paramètres → Capacités → Skills → Importer un skill
Activez et commencez à utiliser
Tester
Utilisation de "openapi-spec-generation". Create an OpenAPI specification for a product catalog API
Résultat attendu:
- openapi: 3.1.0 with info section containing title, description, version
- GET/POST/PUT/DELETE endpoints for products resource
- Product schema with id, name, price, description, category properties
- Pagination and filtering query parameters
- Error responses for 400, 401, 404, 429 status codes
- Bearer token authentication configuration in security schemes
Utilisation de "openapi-spec-generation". Write Spectral validation rules for operation IDs
Résultat attendu:
- Rule checks for presence of operationId in each operation
- Severity level set to error for missing operationId
- Validates operationId follows naming convention pattern
- Reports violations with field path and descriptive message
Audit de sécurité
SûrPure documentation skill containing YAML OpenAPI templates, code examples (Python FastAPI, TypeScript tsoa), and validation patterns. No executable code, no file system access, no network calls. All 126 static findings are false positives: detected cryptographic keywords are data format specifiers in YAML schemas, backticks are markdown formatting in documentation code blocks, URLs are example domains and documentation references, and system keywords are standard OpenAPI syntax.
Facteurs de risque
🌐 Accès réseau (13)
Score de qualité
Ce que vous pouvez construire
إنشاء مواصفات API
تصميم وتوثيق REST APIs مع قوالب OpenAPI 3.1 كاملة بما في ذلك المخططات والأمثلة ومخططات الأمان.
توثيق مبني على الكود
توليد مواصفات OpenAPI من قواعد كود FastAPI أو Express/tsoa الموجودة للتوليد التلقائي لـ SDK.
التحقق من صحة عقود API
إعداد قواعد linting وسير التحقق من صحة لضمان استيفاء مواصفات API لمعايير الجودة والامتثال.
Essayez ces prompts
Generate an OpenAPI 3.1 specification template for a [RESOURCE] API with CRUD endpoints, authentication, and error responses.
Create a Python FastAPI code example that generates an OpenAPI specification for user management with pagination and filtering.
Write Spectral validation rules for OpenAPI specs that enforce operation IDs, descriptions, and security definitions.
Generate an OpenAPI Generator command to create a TypeScript client from an OpenAPI specification file.
Bonnes pratiques
- استخدم $ref للمخططات والمعاملات والاستجابات القابلة لإعادة الاستخدام للحفاظ على الاتساق عبر المواصفات
- أضف أمثلة واقعية في مخططات الطلب والاستجابة لمساعدة مستهلكي API على فهم الاستخدام
- حدد جميع استجابات الأخطاء الممكنة بما في ذلك أخطاء التحقق من الصحة وفشل المصادقة وتحديد معدل الطلب
Éviter
- تجنب الأوصاف العامة أو المفقودة على العمليات والمعلمات وخصائص المخططات
- لا تتخطى تحديد مخططات الأمان حتى بالنسبة لـ APIs الداخلية
- تجنب ترميز عناوين URL للخوادم في المسارات؛ استخدم متغيرات الخوادم للبيئات المختلفة