README

API Tools for Kuick Framework

This package plugs into the Kuick Framework and automatically exposes three HTTP endpoints:

Requirements

• PHP 8.2+
• Kuick Framework ^2.8

Installation

composer require kuick/api-tools

The Kuick Framework auto-discovers the route, guard, and DI config files bundled in this package — no manual wiring is required.

Endpoints

GET /api/doc

Returns a self-contained Swagger UI page that loads the OpenAPI spec from /api/doc.json. No authentication required.

GET /api/doc.json

Returns the OpenAPI specification as JSON. The spec is built at runtime by scanning #[OA\...] attributes in your project's src/ directory (via zircote/swagger-php). No authentication required.

GET /api/ops

Returns a JSON object with full system diagnostics:

{
  "request":              { ... },
  "environment":          { ... },
  "di-config":            { ... },
  "opcache-status":       { ... },
  "apcu-status":          { ... },
  "php-version":          "8.3.x",
  "php-config":           { ... },
  "php-loaded-extensions": "..."
}

Protected by Bearer token — see Configuration below.

Configuration

All settings are read from environment variables. Set them in your .env file or deployment environment.

Ops endpoint security

Example — calling the protected endpoint:

curl -H "Authorization: Bearer my-secret-token" https://your-app.example.com/api/ops

OpenAPI metadata

Example .env snippet:

API_SECURITY_OPS_GUARD_TOKEN=my-secret-token

API_OPENAPI_TITLE=My Project API
API_OPENAPI_DESCRIPTION=Internal REST API for My Project
API_OPENAPI_VERSION=1.0.0

Annotating your API with OpenAPI attributes

DocJsonController scans $projectDir/src for swagger-php attributes at runtime. Decorate your controllers with #[OA\...] attributes to include them in the generated spec:

use OpenApi\Attributes as OA;

#[OA\Get(
    path: '/api/users',
    description: 'Returns a list of users',
    tags: ['Users'],
    responses: [
        new OA\Response(response: 200, description: 'List of users', content: new OA\JsonContent()),
    ]
)]
final class UserListController
{
    public function __invoke(): JsonResponse { ... }
}