What problem does it solve? OrangeHRM's CI enforces OpenAPI v3 annotations on every REST endpoint and Model class via generate-open-api-doc --throw, so a PR with missing or malformed swagger-php annotations fails the build. This Skill provides the exact annotation patterns, shared component refs, and debugging steps needed to write correct @OA\* docblocks the first time. ## Core Features & Use Cases - Endpoint Annotation Recipes: Ready-to-adapt templates for @OA\Get, @OA\Post, @OA\Delete blocks on handler methods (getOne, getAll, create, update, delete), including path parameters, query parameters, and request bodies. - Shared Component Refs: Documents the project's reusable #/components/responses/RecordNotFound, ForbiddenResponse, DeleteResponse, DeleteRequestBody, and the sortOrder/limit/offset parameters so you reference instead of redefine. - Model Schema Rules: Explains the <Plugin>-<ModelName> schema naming convention, aligning @OA\Property entries with setAttributeNames(), nested objects, arrays, and oneOf model variants. - Use Case: You add a new /api/v2/x/widgets endpoint and need the annotations to pass CI. Follow the checklist, use PHP class constants inside annotations for enums and max lengths, then verify locally with php devTools/core/console.php generate-open-api-doc --throw before pushing. ## Quick Start Ask the agent to add OpenAPI annotations to your new endpoint handler methods and Model class following the rest-openapi conventions, then run the generate-open-api-doc command with the throw flag to verify.
