fix(openapi): OAS 3.1 の nullable 記法を type: [T, 'null'] 形式に移行する

[claude]

概要

現在の api/openapi.yaml は openapi: 3.1.0 を宣言しているにもかかわらず、nullable フィールドに OAS 3.0 の記法（nullable: true）を使用している。

OAS 3.1 では nullable キーワードは非推奨であり、正式な記法は JSON Schema の type に null を含める方法である。

影響箇所

以下のフィールドが対象:

スキーマ	フィールド
UserProfile	departmentName
MeResponse	activeTenantId
TenantUser	departmentName
Task	description, assignee, completedAt
TaskCreateRequest	description, assigneeId
TaskUpdateRequest	description, assigneeId
AuditLog	userId, entityType, entityId, ipAddress

修正方針

nullable: true を type: [<元の型>, 'null'] に置き換える。

例:

# Before (OAS 3.0 記法)
activeTenantId: { type: integer, format: int64, nullable: true }

# After (OAS 3.1 記法)
activeTenantId:
  type: [integer, 'null']
  format: int64

$ref を持つフィールド（assignee など）は oneOf を使う形式に変更する:

# Before
assignee: { $ref: "#/components/schemas/UserSummary", nullable: true }

# After
assignee:
  oneOf:
    - $ref: "#/components/schemas/UserSummary"
    - type: 'null'

関連

• OpenAPI Specification 3.1.0: https://spec.openapis.org/oas/v3.1.0#schema-object
• 本問題は PR feat(openapi): 全スキーマの required 配列を整備 (Issue #108) #117 のレビューで指摘された（指摘3）

[win2cot]

@claude go

[claude]

Claude finished @win2cot's task in 4m 10s —— View job • claude/issue-118-20260514-1330 • Create PR ➔

---

OAS 3.1 nullable 記法の移行

• api/openapi.yaml を読み込み、対象箇所を確認する
• nullable: true / nullable: false を OAS 3.1 記法に修正する
  • UserProfile.departmentName → type: [string, 'null']
  • MeResponse.activeTenantId → type: [integer, 'null'] + format: int64
  • TenantUser.departmentName → type: [string, 'null']
  • Task.description → type: [string, 'null']
  • Task.assignee → oneOf: [$ref: UserSummary, type: 'null']
  • Task.completedAt → type: [string, 'null'] + format: date-time
  • TaskDetail.stakeholders — nullable: false を除去（OAS 3.1 ではデフォルト非 null）
  • TaskCreateRequest.description → type: [string, 'null'] + maxLength: 2000
  • TaskCreateRequest.assigneeId → type: [integer, 'null'] + format: int64
  • TaskUpdateRequest.description → type: [string, 'null'] + maxLength: 2000
  • TaskUpdateRequest.assigneeId → type: [integer, 'null'] + format: int64
  • AuditLog.userId → type: [integer, 'null'] + format: int64
  • AuditLog.entityType → type: [string, 'null']
  • AuditLog.entityId → type: [integer, 'null'] + format: int64
  • AuditLog.ipAddress → type: [string, 'null']
• ビルド・検証を実行する（./gradlew check → BUILD SUCCESSFUL）
• コミット・プッシュする

変更内容

api/openapi.yaml に含まれていた nullable: true / nullable: false（OAS 3.0 記法）をすべて OAS 3.1 準拠の記法に移行しました。

• スカラー型（string / integer）: type: [T, 'null'] 形式に変換
• $ref 型（Task.assignee）: oneOf: [$ref, type: 'null'] パターンに変換
• nullable: false（MeResponse.activeTenantId、TaskDetail.stakeholders）: activeTenantId は業務的に null 許容（未テナント選択状態）のため type: [integer, 'null'] に修正、stakeholders は nullable: false を除去

|