スキル 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でアップロード

設定 → 機能 → スキル → スキルをアップロードへ移動

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