openapi

openapi

When to use

Use this skill when adding or updating API documentation, writing OpenAPI annotations on controllers, or validating API specs.

Procedure: Add OpenAPI documentation

1. Gather context — read agents/reference/docs/controller.md for OpenAPI patterns, agents/settings/contexts/api-versioning.md for versioning, and check 2-3 existing controllers for annotation style.
2. Detect tooling — check composer.json for l5-swagger or laravel-openapi, look for @OA\ vs #[OA\ syntax in existing controllers, find the config file.
3. Write annotations — add #[OA\...] attributes to the controller method. Include path, summary, tags, all parameters, and all response codes (200, 401, 403, 404, 422).
4. Define schemas — create or reuse #[OA\Schema] for request/response types. Use $ref for shared types.
5. Validate — run the spec validation (npx @redocly/cli lint or php artisan l5-swagger:generate). Fix any errors.
6. Verify accuracy — compare the documented request/response with the actual controller + FormRequest + Resource to ensure they match.

OpenAPI attributes

Detection

Check the project for OpenAPI tooling:

• Look for darkaonline/l5-swagger or vyuldashev/laravel-openapi in composer.json.
• Check for @OA\ or #[OA\ annotations in controllers.
• Look for config/l5-swagger.php or similar config files.

PHP 8 attribute syntax

Modern Laravel projects use PHP 8 attributes instead of docblock annotations:

#[OA\Get(
    path: '/projects',
    summary: 'List all projects',
    tags: ['Projects'],
    parameters: [
        new OA\Parameter(
            name: 'page',
            in: 'query',
            required: false,
            schema: new OA\Schema(type: 'integer'),
        ),
    ],
    responses: [
        new OA\Response(
            response: 200,
            description: 'Successful operation',
        ),
    ],
)]
public function __invoke(ListProjectsRequest $request): ProjectCollection
{
    // ...
}