openapi-spec-generation
OpenAPI 3.1 仕様書の生成
API ドキュメントの作成と維持には時間と手間がかかり、エラーも発生しやすいです。このスキルは、OpenAPI 3.1 仕様書の包括的なテンプレート、コード例、検証パターンを提供し、API ドキュメントのワークフローを効率化します。
スキルZIPをダウンロード
Claudeでアップロード
設定 → 機能 → スキル → スキルをアップロードへ移動
オンにして利用開始
テストする
「openapi-spec-generation」を使用しています。 商品カタログ API の OpenAPI 仕様書を作成
期待される結果:
- タイトル、説明、バージョンを含む info セクションを持つ openapi: 3.1.0
- 商品リソースの GET/POST/PUT/DELETE エンドポイント
- id、name、price、description、category プロパティを持つ商品スキーマ
- ページネーションとフィルターのクエリパラメータ
- 400、401、404、429 ステータスコードのエラーレスポンス
- セキュリティスキームの Bearer トークン認証設定
「openapi-spec-generation」を使用しています。 操作 ID の Spectral 検証ルールを記述
期待される結果:
- 各操作に operationId の存在をチェックするルール
- missing operationId のエラーレベルを設定
- operationId が命名規則パターンに従うことを検証
- フィールドパスと説明的なメッセージで違反を報告
セキュリティ監査
安全Pure 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.
リスク要因
🌐 ネットワークアクセス (13)
品質スコア
作れるもの
API 仕様書の作成
スキーマ、例、セキュリティスキームを含む完全な OpenAPI 3.1 テンプレートで REST API を設計およびドキュメント化します。
コードファーストドキュメント
既存の FastAPI または Express/tsoa コードベースから OpenAPI 仕様書を生成し、SDK を自動生成します。
API コントラクトの検証
リンティングルールと検証パイプラインを設定して、API 仕様書が品質とコンプライアンス基準を満たしていることを確認します。
これらのプロンプトを試す
[RESOURCE] API のための CRUD エンドポイント、認証、エラーレスポンスを含む OpenAPI 3.1 仕様書テンプレートを生成してください。
ページネーションとフィルター機能を備えたユーザー管理の OpenAPI 仕様書を生成する Python FastAPI のコード例を作成してください。
操作 ID、説明、セキュリティ定義を強制する OpenAPI 仕様書の Spectral 検証ルールを記述してください。
OpenAPI 仕様書ファイルから TypeScript クライアントを作成するための OpenAPI Generator コマンドを生成してください。
ベストプラクティス
- 再利用可能なスキーマ、パラメータ、レスポンスに $ref を使用して、仕様書間の一貫性を維持してください
- リクエストおよびレスポンスキーマに現実世界の例を含め、API 消費者が使用法を 이해しやすくしてください
- 検証エラー、認証失敗、レート制限を含む考えられるすべてのエラーレスポンスを定義してください
回避
- 操作、パラメータ、スキーマプロパティの一般的な説明や説明の欠落は避けてください
- 内部 API でもセキュリティスキームの定義をスキップしないでください
- パスにサーバー URL をハードコーディングすることは避けてください。異なる環境にはサーバー変数を使用してください