openapi-development

name	openapi-development
description	Maintain exported OpenAPI and GraphQL snapshots for php-service-template.

OpenAPI Development

Use This Skill When

• a REST resource changes
• request or response fields change
• GraphQL schema changes
• exported spec snapshots drift in CI

Commands

make generate-openapi-spec
make generate-graphql-spec

Expectations

• .github/openapi-spec/spec.yaml reflects the current REST surface.
• .github/graphql-spec/spec reflects the current GraphQL surface.
• The exported snapshots belong in the same PR as the code change that caused them.

Implementation Notes

• Keep API Platform metadata outside Domain classes.
• Prefer DTO and processor patterns for writes.
• When adding a new endpoint, validate the resource config, serialization, and generated snapshot together.

Verification

After export:

make generate-openapi-spec
make generate-graphql-spec
make unit-tests
make integration-tests

If the change is architectural or documentation-facing, follow with documentation-sync.