API 仕様書で定義すべきこと
OpenAPI 形式の構成要素と Python による自動検証

{
  "type": "https://errors.example.com/validation-error",
  "title": "Validation Error",
  "status": 400,
  "detail": "リクエストパラメータに不備があります",
  "instance": "/orders/create",
  "errors": [
    {
      "field": "quantity",
      "message": "1 以上の整数を指定してください",
      "rejectedValue": -1
    },
    {
      "field": "productId",
      "message": "必須項目です",
      "rejectedValue": null
    }
  ],
  "traceId": "550e8400-e29b-41d4-a716-446655440000"
}

openapi: "3.1.0"
info:
  title: Order Service API
  version: "2.3.0"
  description: |
    注文管理サービスの REST API 仕様書。
    認証には Bearer Token（JWT）を使用する。
  contact:
    name: Backend Team
    email: backend@example.com
  license:
    name: Private

servers:
  - url: https://api.example.com/v2
    description: 本番環境
  - url: https://staging-api.example.com/v2
    description: ステージング環境

security:
  - bearerAuth: []   # デフォルトで全エンドポイントに認証を適用

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
  schemas:
    Order:
      type: object
      required: [id, status, totalAmount, createdAt]
      properties:
        id:
          type: string
          format: uuid
          example: "550e8400-e29b-41d4-a716-446655440000"
        status:
          type: string
          enum: [pending, confirmed, shipped, delivered, cancelled]
        totalAmount:
          type: integer
          description: 合計金額（税込み、円）
          minimum: 0
        createdAt:
          type: string
          format: date-time
    Error:
      type: object
      required: [title, status, detail]
      properties:
        type:
          type: string
          format: uri
        title:
          type: string
        status:
          type: integer
        detail:
          type: string
        traceId:
          type: string

paths:
  /orders:
    get:
      summary: 注文一覧を取得する
      operationId: listOrders
      tags: [orders]
      parameters:
        - name: limit
          in: query
          schema:
            type: integer
            default: 20
            minimum: 1
            maximum: 100
          description: 1 ページの取得件数
        - name: cursor
          in: query
          schema:
            type: string
          description: ページネーション用カーソル
        - name: status
          in: query
          schema:
            type: string
            enum: [pending, confirmed, shipped, delivered, cancelled]
          description: ステータスでフィルタ
      responses:
        "200":
          description: 注文一覧取得成功
          headers:
            X-RateLimit-Limit:
              schema:
                type: integer
              description: 1分あたりの上限リクエスト数
            X-RateLimit-Remaining:
              schema:
                type: integer
              description: 残りリクエスト数
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Order'
                  hasMore:
                    type: boolean
                  nextCursor:
                    type: string
                    nullable: true
        "401":
          description: 認証失敗
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        "429":
          description: レート制限超過
          headers:
            Retry-After:
              schema:
                type: integer
              description: 次のリクエストまでの待機秒数
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

"""
openapi-spec-validator で仕様ファイルの構文・スキーマ整合性をチェックする。

インストール:
  pip install openapi-spec-validator pyyaml
"""
import sys
import yaml
from openapi_spec_validator import OpenAPIV31SpecValidator
from openapi_spec_validator.exceptions import OpenAPISpecValidatorError

def validate_spec(path: str) -> None:
    with open(path, encoding="utf-8") as f:
        spec = yaml.safe_load(f)

    validator = OpenAPIV31SpecValidator(spec)
    errors = list(validator.iter_errors())

    if not errors:
        print(f"✅ {path} — 仕様ファイルに問題はありません")
        # エンドポイント一覧を表示
        paths = spec.get("paths", {})
        print(f"\n登録エンドポイント数: {sum(len(v) for v in paths.values())}")
        for path_key, methods in sorted(paths.items()):
            for method, op in methods.items():
                op_id = op.get("operationId", "-")
                summary = op.get("summary", "-")
                print(f"  {method.upper():7} {path_key:<40} {op_id} — {summary}")
    else:
        print(f"❌ {path} — {len(errors)} 件のエラーが見つかりました\n")
        for i, err in enumerate(errors, 1):
            print(f"  [{i}] {err.message}")
            if err.path:
                print(f"       場所: {' > '.join(str(p) for p in err.path)}")
        sys.exit(1)

if __name__ == "__main__":
    spec_file = sys.argv[1] if len(sys.argv) > 1 else "openapi.yaml"
    validate_spec(spec_file)

"""
Flask アプリに登録されたルートと OpenAPI 仕様のエンドポイントを比較し、
「仕様にあるが実装がない」「実装にあるが仕様がない」エンドポイントを検出する。

インストール:
  pip install pyyaml flask
"""
import re
import yaml
from pathlib import Path


def get_spec_endpoints(spec_path: str) -> set[tuple[str, str]]:
    """OpenAPI 仕様からエンドポイント（method, path）セットを返す。"""
    spec = yaml.safe_load(Path(spec_path).read_text(encoding="utf-8"))
    endpoints = set()
    for path, methods in spec.get("paths", {}).items():
        for method in methods:
            if method.lower() not in ("get", "post", "put", "patch", "delete"):
                continue
            # OpenAPI の {id} 形式を Flask の  形式に変換
            flask_path = re.sub(r"\{(\w+)\}", r"<\1>", path)
            endpoints.add((method.upper(), flask_path))
    return endpoints


def get_flask_endpoints(app) -> set[tuple[str, str]]:
    """Flask アプリからエンドポイントセットを返す。"""
    endpoints = set()
    for rule in app.url_map.iter_rules():
        for method in rule.methods or []:
            if method in ("HEAD", "OPTIONS"):
                continue
            endpoints.add((method, rule.rule))
    return endpoints


if __name__ == "__main__":
    # Flask アプリのインポート（実際の app モジュールに合わせて変更）
    from app import create_app  # type: ignore
    flask_app = create_app()

    spec_eps = get_spec_endpoints("openapi.yaml")
    flask_eps = get_flask_endpoints(flask_app)

    only_in_spec = spec_eps - flask_eps
    only_in_flask = flask_eps - spec_eps

    if only_in_spec:
        print("⚠️  仕様に定義があるが実装が存在しないエンドポイント:")
        for method, path in sorted(only_in_spec):
            print(f"   {method:7} {path}")

    if only_in_flask:
        print("\n⚠️  実装が存在するが仕様に定義がないエンドポイント:")
        for method, path in sorted(only_in_flask):
            print(f"   {method:7} {path}")

    if not only_in_spec and not only_in_flask:
        print("✅ 仕様と実装のエンドポイントは一致しています")

"""
schemathesis でステージング環境に対して OpenAPI 仕様に基づく
自動テストを実行し、仕様との不整合を検出する。

インストール:
  pip install schemathesis

実行:
  python -m schemathesis run openapi.yaml \
    --url https://staging-api.example.com/v2 \
    --auth-type bearer --auth "$TOKEN" \
    --checks all
"""

# pytest との組み合わせ（CI 用）
import schemathesis

schema = schemathesis.from_path(
    "openapi.yaml",
    base_url="https://staging-api.example.com/v2",
)

@schema.parametrize()
def test_api(case):
    """仕様書に定義されたすべてのエンドポイントに対してランダムな値でリクエストを送り、
    レスポンスが仕様のスキーマに準拠しているか検証する。"""
    response = case.call()
    case.validate_response(response)