mcpField
O
openapi-spec-generation

openapi-spec-generation

github.com/wshobson開発41.9k16.6k 回インストール2 週間前に更新
リポジトリ

openapi-spec-generation について

OpenAPI 3.1仕様の作成、保守、検証を支援するスキルです。新規または既存のAPIに取り組む設計者や開発者向けに、設計先行、コード先行、両者を組み合わせた方法を扱います。

主な機能

  1. 01OpenAPI 3.1の構造とパターン
  2. 02設計先行・コード先行・混合のワークフロー
  3. 03仕様の検証と実装の照合
  4. 04再利用可能なスキーマ、例、エラー文書
  5. 05SDK生成とAPIポータルのガイダンス

活用シーン

  1. 01実装前のAPI契約の作成
  2. 02既存コードから仕様を生成
  3. 03API実装と仕様の照合
  4. 04SDK生成に向けた仕様の準備

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/wshobson/agents --skill openapi-spec-generation

インストール後、Claude Code で/openapi-spec-generationを入力して読み込まれたか確認します。

同梱ファイルreferences/code-first-and-tooling.mdreferences/details.md

詳細

OpenAPI 仕様の生成

RESTful API 向けの OpenAPI 3.1 仕様を作成、維持、検証するための包括的なパターンです。

このスキルを使用する場面

  • API ドキュメントをゼロから作成する場合
  • 既存のコードから OpenAPI 仕様を生成する場合
  • API コントラクトを設計する場合（設計優先アプローチ）
  • API 実装を仕様に照らして検証する場合
  • 仕様からクライアント SDK を生成する場合
  • API ドキュメントポータルを構築する場合

中核となる概念

1. OpenAPI 3.1 の構造
openapi: 3.1.0
info:
  title: API Title
  version: 1.0.0
servers:
  - url: https://api.example.com/v1
paths:
  /resources:
    get: ...
components:
  schemas: ...
  securitySchemes: ...
2. 設計アプローチ
アプローチ説明最適な用途
設計優先コードの前に仕様を書く新規 API、コントラクト
コード優先コードから仕様を生成する既存の API
ハイブリッドコードに注釈を付け、仕様を生成する進化する API

テンプレートと詳細な実例

完全なテンプレートライブラリと詳細な実例は references/details.md にあります。具体的なテンプレートが必要な場合は、そのファイルを参照してください。

ベストプラクティス

推奨事項
  • $ref を使用する - スキーマ、パラメータ、レスポンスを再利用します
  • 例を追加する - 実際の値は利用者の役に立ちます
  • エラーを文書化する - 考えられるすべてのエラーコードを記載します
  • API をバージョン管理する - URL またはヘッダーで行います
  • セマンティックバージョニングを使用する - 仕様の変更に対して行います
非推奨事項
  • 一般的な説明を使用しない - 具体的に記述します
  • セキュリティを省略しない - すべてのスキームを定義します
  • nullable を忘れない - null について明示します
  • スタイルを混在させない - 全体を通して一貫した命名にします
  • URL をハードコードしない - サーバー変数を使用します

コメント

Markdown 対応