mcpField
O
openapi

openapi

github.com/oakoss開発21191 回インストール12 週間前に更新
リポジトリ

openapi について

openapiは、API開発者向けのOpenAPI 3.1仕様ガイドです。APIコントラクトやJSON Schemaとの互換性、型生成、仕様上のよくある問題を扱います。

主な機能

  1. 01HTTP APIコントラクトの定義
  2. 02エンドポイント、スキーマ、認証の記述
  3. 03JSON Schema互換性の利用
  4. 04型生成とドキュメント作成の指針
  5. 05仕様上のよくある誤りの確認

活用シーン

  1. 01REST APIの設計
  2. 02TypeScript、Python、Goのクライアント型生成
  3. 03リクエストとレスポンスの検証
  4. 04コントラクト優先のAPI開発

インストール

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

$npx skills add https://github.com/oakoss/agent-skills --skill openapi

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

同梱ファイル

SKILL.md と一緒にインストールされる参考資料やスクリプト。

references/
code-generation.md
data-types.md
documentation.md
schema-design.md

詳細

OpenAPI

概要

OpenAPI Specification（OAS）3.1は、HTTP APIを記述するための業界標準です。エンドポイント、リクエスト／レスポンスのスキーマ、認証、エラー形式を網羅する、機械可読な契約を定義します。OpenAPI 3.1はJSON Schema Draft 2020-12の厳密なスーパーセットであり、データ検証や型生成においてJSON Schemaとの完全な互換性を実現します。

使用する場面： REST APIの設計、型付きクライアント（TypeScript、Python、Go）の生成、インタラクティブなドキュメントの作成、リクエスト／レスポンスのペイロードの検証、契約ファーストのAPI開発、APIゲートウェイの設定。

使用しない場面： GraphQL API（GraphQLスキーマを使用）、gRPCサービス（Protocol Buffersを使用）、WebSocket専用プロトコル、ネットワーク境界を越えることのない内部関数呼び出し。

クイックリファレンス

パターン要素主なポイント
ドキュメントのルートopenapi、info、paths最上位にopenapi: '3.1.0'が必要
パス項目/resources/{id}パスパラメーターには波括弧を使用
オペレーションget、post、put、delete、patch各オペレーションにoperationIdとresponsesが必要
パラメーターin: path|query|header|cookieパスパラメーターは常にrequired: true
リクエストボディrequestBody.contentメディアタイプ（application/json）をキーとして指定
レスポンスresponses.200.content各オペレーションに少なくとも1つのレスポンスが必要
コンポーネント参照$ref: '#/components/schemas/Name'スキーマ、パラメーター、レスポンスを再利用
スキーマの型type: string|number|integer|boolean|array|object3.1では配列でtype: ["string", "null"]をサポート
合成oneOf、anyOf、allOf多相性と共通部分型をモデル化
識別子discriminator.propertyNameoneOf／anyOfを使うコードジェネレーター向けのヒント
セキュリティsecuritySchemes + 最上位のsecurityBearer、APIキー、OAuth2、OpenID Connect
タグオペレーションのtagsドキュメント内でオペレーションをグループ化
型生成openapi-typescript実行時依存のない、仕様からのTypeScript型生成
型付きfetchopenapi-fetch生成された型を使う、型安全なHTTPクライアント
React Queryopenapi-react-query仕様から生成される、型安全なReact Queryフック
スキーマファーストzod-openapiZodスキーマからOpenAPIドキュメントを生成

よくある間違い

間違い正しいパターン
3.1 で nullable: true を使用するtype: ["string", "null"] を使用します（3.0 の構文は廃止されています）
オペレーションに operationId がないコード生成のため、必ず一意の operationId を設定します
パスパラメーターが required に含まれていないパスパラメーターは常に必須です（required: true）
あらゆる場所でインラインスキーマを使用するcomponents/schemas に切り出し、$ref を使用します
required フィールドが競合する allOfrequired 配列を統合します。allOf はそれらを結合します
共通プロパティなしでディスクリミネーターを使用するoneOf／anyOf 内のすべてのスキーマに、ディスクリミネーターのプロパティを含める必要があります
レスポンスの description が空であるすべてのレスポンスに意味のある description が必要です
properties なしで type: object を使用する必ず properties を定義するか、additionalProperties を使用します
循環する $ref チェーン遅延解決で循環を断つか、スキーマを再構成します
3.0 と 3.1 の構文を混在させるどちらか一方のバージョンを選びます。3.1 では nullable が廃止され、exclusiveMinimum が数値に変更されています

委任

  • API 設計レビュー：Task エージェントを使用して、仕様の完全性と一貫性を監査します
  • 型生成：Explore エージェントを使用して、プロジェクト固有の OpenAPI ツール設定を探します
  • コードレビュー：生成されたクライアントの使用パターンを code-reviewer エージェントに委任します

typescript-patterns スキルを利用できる場合は、高度な TypeScript の型付けに関する質問を委任します。

参考資料

コメント

Markdown 対応