Frontend Api Doc Governance

2. Frontend consumption completeness

• Required permissions per route documented.
• Tenant/scope constraints documented (tenant/team/project/own).
• Idempotency behavior documented for write routes.
• Pagination/sorting/filtering contract documented for list routes.
• Field-level notes for nullable, enum, deprecated, and computed fields.
• At least one realistic request/response example per endpoint.

3. Fidelity checks (docs vs implementation)

• OpenAPI matches implemented route signature and payload.
• Authorization policy bindings match required permissions.
• Example payloads reflect real field names and real status behavior.
• Breaking changes include version bump and migration notes.

4. Change communication

• Changelog section with what changed and why.
• Frontend impact section with migration actions (if any).
• Backward-compatibility classification: non-breaking or breaking.

Required Artifacts

For each API change, update:

• OpenAPI file in docs/openapi/
• Authorization contract/bindings if permission changed
• Module docs affected (architecture/integrations/entities/etc.)

Review Workflow

1. Identify all touched endpoints.
2. Generate contract diff (before vs after) for paths/schemas/statuses.
3. Validate permissions and tenant scope against policy docs.
4. Validate examples against real schema.
5. Produce pass/fail verdict with blocking gaps.

Output Template

• API change summary:
• Endpoints affected:
• Payload changes:
• Status/error changes:
• Permission/policy changes:
• Frontend impact:
• Compatibility: non-breaking | breaking
• Required migration actions:
• Missing documentation items:
• Gate verdict: pass | fail

Hard Fail Conditions

• Endpoint changed without OpenAPI update.
• Permission changed without policy/binding update.
• Payload/status changed without example updates.
• Breaking change without versioning and migration notes.