openapi-development
Contribute to the API Platform OpenAPI customization layer — endpoint factories, request/response/schema factories, and transformers — keeping the generated spec valid and diff-stable. Use when adding
SKILL.mdplugins/php-backend-sdlc/skills/openapi-development/SKILL.md
GitHubOpenAPI Development Skill
Profile keys consumed
framework.api_platformarchitecture.source_rootarchitecture.shared_contextmake.phpinsightsquality.phpinsights.qualityquality.phpinsights.architecturequality.phpinsights.stylequality.phpinsights.complexityci.workflows
This skill applies only when framework.api_platform is a version
string; when it is false, skip with a capability-absent note.
The OpenAPI layer referenced throughout is
<architecture.source_root>/<architecture.shared_context>/Application/OpenApi/.
When architecture.shared_context is null, locate the OpenApi
directory under the Application layer of the bounded context that owns
API composition instead.
Context (Input)
- Adding new OpenAPI endpoint factories under the OpenAPI layer's
Factory/Endpoint/directory - Adding/editing request/response/schema factories under
Factory/ - Adding/editing transformers/processors that modify the generated spec
- Fixing OpenAPI validation errors from Spectral lint, OpenAPI diff, or Schemathesis runs
Task (Function)
Develop and maintain OpenAPI specification generation in a way that:
- Keeps
quality.phpinsights.*scores intact (defaults: quality, architecture, and style100; complexity94— raise-only floors: a profile may tighten them, never relax them; fix the code, never the thresholds) - Preserves immutability when working with API Platform OpenAPI models
(
with*()methods) - Produces a spec that passes Spectral and stays diff-stable
Success Criteria:
- The repository's spec-generation target produces the committed spec file, and its Spectral validation target passes (see Testing / Validation below for target discovery).
Architecture Overview
The OpenAPI layer follows a layered customization approach:
<architecture.source_root>/<architecture.shared_context>/Application/OpenApi/
├── Builder/ # Build common OpenAPI pieces
├── Extractor/ # Extract example values / payload fragments
├── Factory/ # Endpoint/Request/Response/Schema/UriParameter factories
├── Transformer/ # Transform/modify OpenAPI operations, parameters, responses
├── ValueObject/ + Enum/ # Strongly typed OpenAPI-related value objects
└── Factory/OpenApiFactory.php # Main coordinator (decorator)
config/services.yaml decorates API Platform's OpenAPI factory with
the application's coordinator factory, which receives a tagged iterator
of endpoint factories. Upstream reference wiring:
# config/services.yaml — decorator + tagged iterator
App\Shared\Application\OpenApi\Factory\OpenApiFactory: ~ # decorates API Platform's OpenAPI factory
# arguments include: !tagged_iterator 'app.openapi_endpoint_factory'
Key Principles (Keep Complexity Low)
Single Responsibility: one class = one transformation.
Immutability: prefer
with*()methods; avoid mutating nested arrays unless API Platform forces it.OPERATIONS constant: avoid chaining
withGet/withPost/...repeatedly — loop over a constant with dynamicwith/getcalls:private const OPERATIONS = ['Get', 'Post', 'Put', 'Patch', 'Delete']; private function transformPathItem(PathItem $pathItem): PathItem { foreach (self::OPERATIONS as $operation) { $pathItem = $pathItem->{'with' . $operation}( $this->transformOperation($pathItem->{'get' . $operation}()) ); } return $pathItem; }Readable guard clauses: prefer early returns (
nulloperation, non-array parameters) over deep nesting.Functional style:
array_map,array_filter,array_keysover procedural mutation with intermediate arrays.Small methods: keep methods around 20 lines and cyclomatic complexity per method below 5; extract helpers that take explicit inputs, return transformed output, and mutate no external state.
Avoid
empty(): use explicit checks —$array === []for arrays,$value === ''(with explicitnullhandling) for strings.
Never add suppression annotations to silence quality findings — refactor to the root cause instead.
How to Add New Components
Adding a New Transformer
- Create a focused class under the OpenAPI layer's
Transformer/directory. - Implement a single public entry method, e.g.
transform(OpenApi $openApi): OpenApi. - Iterate paths using
array_keys($openApi->getPaths()->getPaths()). - Apply changes per
PathItemusing anOPERATIONSconstant + dynamicwith/getcalls. - Do NOT create new directories (e.g.
Augmenter/,Enricher/,Helper/). New OpenAPI transformation classes belong inTransformer/. Do not duplicate the purpose of directories that already exist in the layer.
Adding a New Endpoint Factory
- Implement the layer's endpoint-factory interface (e.g.
EndpointFactoryInterface) underFactory/Endpoint/. - It is auto-tagged by
_instanceofinconfig/services.yaml. - It will be invoked by the coordinator
OpenApiFactory.
Testing / Validation
The profile make map defines no logical keys for OpenAPI spec
generation or validation; discover the repository's targets in its
Makefile (and check ci.workflows for an OpenAPI validation workflow).
Note the gap if none exist. Run locally in this order — generate, lint,
diff, then property-based validation. Upstream reference targets:
make generate-openapi-spec # exports .github/openapi-spec/spec.yaml
make validate-openapi-spec # Spectral lint via ./scripts/validate-openapi-spec.sh
make openapi-diff # diff-stability / breaking-change check
make schemathesis-validate # Schemathesis: Examples and Coverage phases
After code changes, run the target mapped by make.phpinsights to
confirm the quality.phpinsights.* floors still hold.
Related Skills
- complexity-management for refactoring when PHPInsights fails
- documentation-sync when spec changes require docs updates