المهارات openapi-spec-generation
📦

openapi-spec-generation

آمن

Generate OpenAPI 3.1 Specifications

متاح أيضًا من: wshobson

Create comprehensive OpenAPI 3.1 specifications for REST APIs using design-first, code-first, or hybrid approaches. Includes templates, validation patterns, and SDK generation guidance.

يدعم: Claude Codex Code(CC)
🥉 74 برونزي
1

تنزيل ZIP المهارة

2

رفع في Claude

اذهب إلى Settings → Capabilities → Skills → Upload skill

3

فعّل وابدأ الاستخدام

اختبرها

استخدام "openapi-spec-generation". Create an OpenAPI 3.1 spec for a users API

النتيجة المتوقعة:

A complete OpenAPI specification with /users endpoint (GET, POST), /users/{id} endpoint (GET, PATCH, DELETE), User schema with uuid, email, name, status, role fields, Bearer authentication, pagination parameters, and standard error responses.

استخدام "openapi-spec-generation". Add rate limiting headers to responses

النتيجة المتوقعة:

Updated spec with RateLimited response including Retry-After, X-RateLimit-Limit, and X-RateLimit-Remaining headers with integer schemas.

استخدام "openapi-spec-generation". Generate TypeScript client from spec

النتيجة المتوقعة:

TypeScript fetch client with typed methods for each endpoint, proper authentication headers, and TypeScript interfaces matching the schema.

التدقيق الأمني

آمن
v1 • 2/24/2026

This skill provides instructional documentation for OpenAPI specification generation. All static findings are false positives: shell command examples are documentation samples, hardcoded URLs are example domains (example.com, localhost), JWT references are standard API authentication definitions, and there is no malicious code execution. The skill is safe for marketplace publication.

2
الملفات التي تم فحصها
1,064
الأسطر التي تم تحليلها
3
النتائج
1
إجمالي عمليات التدقيق
مشكلات متوسطة المخاطر (1)
resources/implementation-playbook.md:897-977SKILL.md:31-35
Documentation Shell Command Examples
The implementation playbook contains example shell commands (npm install, spectral lint) for users to learn from. These are instructional examples, not executable code.
مشكلات منخفضة المخاطر (2)
resources/implementation-playbook.md:28-1027
Example URLs in Documentation
Documentation contains example URLs (api.example.com, localhost) used as placeholders in API specification examples.
resources/implementation-playbook.md:495-510
JWT Authentication Reference
OpenAPI spec examples reference JWT Bearer token authentication. JWT is a standard industry authentication mechanism, not a cryptographic vulnerability.
تم تدقيقه بواسطة: claude

درجة الجودة

38
الهندسة المعمارية
100
قابلية الصيانة
87
المحتوى
50
المجتمع
96
الأمان
100
الامتثال للمواصفات

ماذا يمكنك بناءه

New API Design

Create OpenAPI specs for new APIs using design-first approach with comprehensive examples for authentication, pagination, and error handling.

Existing API Documentation

Generate documentation from existing codebases using FastAPI or Express with tsoa annotations.

SDK Generation Workflow

Generate client SDKs in multiple languages from OpenAPI specs for frontend and external consumers.

جرّب هذه الموجهات

Create Basic API Spec 
Create an OpenAPI 3.1 specification for a [RESOURCE] API with CRUD operations. Include authentication via Bearer token, pagination support, and standard error responses.
Add Authentication Security 
Add JWT Bearer authentication and API key security schemes to an existing OpenAPI spec. Include 401 and 403 error responses.
Generate Python Client SDK 
Generate a Python client SDK from this OpenAPI specification. Include authentication handling and proper error types.
Validate and Lint Spec 
Create Spectral linting rules for this OpenAPI spec that enforce operation IDs, require descriptions, and validate security definitions.

أفضل الممارسات

  • Use $ref to reuse schemas, parameters, and responses across the spec
  • Include real-world examples in the spec to help API consumers
  • Define all possible error codes and include descriptive messages
  • Version your API in the URL path and use semantic versioning for spec changes

تجنب

  • Avoid generic descriptions like 'Gets a resource' - be specific about what is returned
  • Do not skip security definitions - every endpoint should have authentication documented
  • Do not mix naming conventions - stay consistent with camelCase or snake_case throughout

الأسئلة المتكررة

What is the difference between design-first and code-first?
Design-first writes the OpenAPI spec before writing code. Code-first generates the spec from code annotations. Design-first is better for new APIs and contracts. Code-first is better for existing codebases.
Which languages are supported for code-first generation?
The skill includes examples for Python with FastAPI and TypeScript with Express/tsoa. Other frameworks like Spring Boot, Rails, and NestJS have their own OpenAPI generation tools.
How do I validate my OpenAPI spec?
Use Spectral for linting with custom rules. Use Redocly for bundle validation. Both can be run from command line and integrated into CI/CD pipelines.
Can this skill generate server code?
No - this skill focuses on specification creation and validation. Use OpenAPI Generator for generating server stubs and client SDKs from specs.
What authentication schemes are supported?
OpenAPI supports API Key, Bearer/JWT, OAuth 2.0, and HTTP authentication. The skill includes examples for Bearer token and API Key schemes.
How do I version my API spec?
Common approaches include URL versioning (/v1/, /v2/), header versioning, or query parameter versioning. The spec version in the info object tracks spec changes.

تفاصيل المطور

المؤلف

sickn33

الترخيص

MIT

المستودع

https://github.com/sickn33/antigravity-awesome-skills/tree/main/skills/openapi-spec-generation

مرجع

main

بنية الملفات

📁 resources/

📄 implementation-playbook.md

📄 SKILL.md