openapi-specification

OpenAPI 仕様

REST API コントラクト向けの OpenAPI 3.x 仕様を設計、検証、保守します。 スキーマパターン、セキュリティスキーム、バージョン管理、コード生成との連携を扱います。

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

• OpenAPI 仕様をゼロから新規作成する
• 既存の仕様にエンドポイントやスキーマを追加する
• API コントラクトの正確性を確認または検証する
• OpenAPI 定義からコードを生成するよう設定する
• 大規模 API 向けに再利用可能なスキーマコンポーネントを設計する
• API 仕様にセキュリティスキームを実装する
• API のバージョン管理と非推奨化を管理する

クイックリファレンス

リソース	目的	読み込むタイミング
references/spec-patterns.md	スキーマパターン、セキュリティスキーム、検証、バージョン管理、再利用可能なコンポーネント	仕様を設計またはレビューするとき

---

ワークフロー

Phase 1: Design       → Define API overview, resources, and operations
Phase 2: Schema       → Build data models with reusable components
Phase 3: Validate     → Lint and verify the spec for correctness
Phase 4: Integrate    → Generate docs, SDKs, and contract tests

---

フェーズ 1：API 設計

仕様を書き始める前に、概要レベルの設計を行います。

1. リソースを特定する -- この API が公開する名詞は何ですか？
2. 操作を整理する -- 各リソースにはどの CRUD 操作やカスタムアクションが適用されますか？
3. 関係を定義する -- リソース同士はどのように参照し合いますか？
4. 認証を計画する -- どのセキュリティスキームが必要ですか？
5. 規約を定める -- 命名スタイル、ページネーション、エラー形式

仕様のひな形

openapi: 3.1.0
info:
  title: [API Name]
  version: 1.0.0
  description: [What this API does]
paths:
  /resources:
    get:
      summary: List resources
      operationId: listResources
    post:
      summary: Create a resource
      operationId: createResource
  /resources/{id}:
    get:
      summary: Get a resource
      operationId: getResource
components:
  schemas: {}
  securitySchemes: {}

---

フェーズ 2：スキーマ設計

再利用できるよう、components/schemas を使ってデータモデルを構築します。

• 共有スキーマの参照には $ref を使います -- 定義を重複させないでください
• 合成には allOf を使い、多態性には oneOf / anyOf を使います
• すべてのスキーマとプロパティに example 値を追加します
• 暗黙の動作に頼らず、required 配列を明示します
• null 許容フィールドは type: [string, "null"]（3.1）または nullable: true（3.0）で記述します

---

フェーズ 3：検証

仕様の変更をコミットする前に検証を実行します。

# Spectral (recommended)
spectral lint openapi.yaml

# Redocly
redocly lint openapi.yaml

# swagger-cli
swagger-cli validate openapi.yaml

よくある検証の問題

問題	修正方法
operationId がない	すべての操作に一意の operationId を追加します
未使用のスキーマ	components から削除するか、$ref を追加します
レスポンスの description がない	すべてのレスポンスコードに description を追加します
パスパラメーターがパスに含まれていない	パス内の {param} とパラメーター定義を一致させます
2xx レスポンスが定義されていない	各操作に少なくとも 1 つの成功レスポンスを追加します

---

フェーズ 4：連携

検証済みの仕様を使って、後続の成果物を生成します。

• ドキュメント：Redoc、Swagger UI、Stoplight
• クライアント SDK：openapi-generator、autorest、orval
• サーバースタブ：サーバーテンプレートを使った openapi-generator
• コントラクトテスト：Schemathesis、Dredd、Prism

---

品質チェックリスト

• すべてのパスに operationIds がある
• HTTP メソッドがリソースの操作に合っている（GET は読み取り、POST は作成など）
• すべてのレスポンスに description とスキーマがある
• 操作単位またはグローバルレベルでセキュリティ要件が定義されている
• リクエストボディとレスポンスボディに例がある
• 命名規則が統一されている（camelCase、snake_case -- どちらかを選択）
• 提供終了予定のエンドポイントに非推奨化フィールドが設定されている
• 仕様がリンターをエラーなしで通過する

---

アンチパターン

• スキーマをインラインで記述しないでください -- 再利用するものには $ref で components/schemas を参照します
• 1 つの仕様ファイルに複数の API バージョンを混在させないでください
• 作成操作に 200 OK を使わないでください -- 201 Created を使います
• エラーレスポンスのスキーマを省略しないでください -- 4xx と 5xx を一貫して記述します
• 明確な理由なく additionalProperties: true を使わないでください