<?php
// composer.json excerpt for OpenApi for PHP
{
    "require-dev": {
        "zircote/swagger-php": "^4.x"
    }
}

// Command to install the library
// composer require --dev zircote/swagger-php

// Minimal script to generate OpenAPI documentation
// generate-openapi.php
<?php
require __DIR__ . '/vendor/autoload.php';

$openapi = \OpenApi\Generator::scan([
    __DIR__ . '/src', // Scan your API controllers/models here
    // __DIR__ . '/config' // Potentially scan a config directory for global definitions
]);

header('Content-Type: application/json');
echo $openapi->toJson();
?>

<?php
// src/Controller/UserController.php
namespace App\Controller;

use OpenApi\Annotations as OA;

/**
 * @OA\Info(
 *      version="1.0.0",
 *      title="User Management API",
 *      description="API for managing user resources.",
 *      @OA\Contact(
 *          email="support@example.com"
 *      )
 * )
 * @OA\Server(
 *      url="http://localhost:8000/api",
 *      description="Development API Server"
 * )
 */
class UserController
{
    /**
     * @OA\Get(
     *      path="/users/{id}",
     *      summary="Retrieve a specific user",
     *      operationId="getUserById",
     *      tags={"Users"},
     *      @OA\Parameter(
     *          name="id",
     *          in="path",
     *          required=true,
     *          description="ID of the user to retrieve",
     *          @OA\Schema(
     *              type="integer",
     *              format="int64"
     *          )
     *      ),
     *      @OA\Response(
     *          response=200,
     *          description="Successful operation",
     *          @OA\JsonContent(
     *              type="object",
     *              @OA\Property(property="id", type="integer", example=1),
     *              @OA\Property(property="name", type="string", example="John Doe"),
     *              @OA\Property(property="email", type="string", format="email", example="john.doe@example.com")
     *          )
     *      ),
     *      @OA\Response(
     *          response=404,
     *          description="User not found"
     *      )
     * )
     */
    public function getUser(int $id)
    {
        // Implement actual logic to fetch user by ID
        // return json_encode(['id' => $id, 'name' => 'John Doe', 'email' => 'john.doe@example.com']);
    }
}

<?php
// src/Model/User.php - A dedicated schema for User data
namespace App\Model;

use OpenApi\Annotations as OA;

/**
 * @OA\Schema(
 *      schema="User",
 *      title="User Model",
 *      description="Represents a user in the system.",
 *      required={"name", "email"},
 *      @OA\Property(property="id", type="integer", format="int64", description="Unique identifier for the user.", readOnly=true, example=101),
 *      @OA\Property(property="name", type="string", description="Full name of the user.", example="Jane Doe"),
 *      @OA\Property(property="email", type="string", format="email", description="Email address of the user.", example="jane.doe@example.com"),
 *      @OA\Property(property="status", type="string", enum={"active", "inactive", "pending"}, default="pending", description="Current status of the user."),
 *      @OA\Property(property="roles", type="array", @OA\Items(type="string"), description="List of roles assigned to the user.", example={"admin", "editor"})
 * )
 */
class User
{
    // ... User properties and methods
}

// src/Controller/UserController.php (Continuing from previous example)
namespace App\Controller;

use OpenApi\Annotations as OA;
use App\Model\User;

class UserController
{
    // ... (previous getUser method and global annotations)

    /**
     * @OA\Post(
     *      path="/users",
     *      summary="Create a new user",
     *      operationId="createUser",
     *      tags={"Users"},
     *      @OA\RequestBody(
     *          required=true,
     *          description="User data for creation",
     *          @OA\JsonContent(ref="#/components/schemas/User") // Reference the User schema
     *      ),
     *      @OA\Response(
     *          response=201,
     *          description="User created successfully",
     *          @OA\JsonContent(ref="#/components/schemas/User")
     *      ),
     *      @OA\Response(
     *          response=400,
     *          description="Invalid input data"
     *      ),
     *      @OA\Response(
     *          response=409,
     *          description="User with this email already exists"
     *      )
     * )
     */
    public function createUser()
    {
        // Implement actual logic to create a user
        // Assume request body is validated against the User schema
        // return json_encode(['id' => 102, 'name' => 'Jane Doe', 'email' => 'jane.doe@example.com']);
    }
}

<?php
// bin/generate-openapi.php - Updated script for file output
<?php
require __DIR__ . '/vendor/autoload.php';

$openapi = \OpenApi\Generator::scan([
    __DIR__ . '/../src',
    __DIR__ . '/../config' // If you have global annotations in a config file
]);

$outputFile = __DIR__ . '/../public/openapi.json';
file_put_contents($outputFile, $openapi->toJson(JSON_PRETTY_PRINT));

echo "OpenAPI documentation generated to {$outputFile}\n";
?>

# public/index.php - Example for serving Swagger UI (requires Swagger UI to be present in 'public/swagger-ui')
<?php
// This is a minimal example. In a real application, you'd use a routing framework.

$requestUri = parse_url($_SERVER['REQUEST_URI'], PHP_URL_PATH);

if ($requestUri === '/docs' || $requestUri === '/docs/') {
    header('Location: /docs/index.html');
    exit();
} elseif (strpos($requestUri, '/docs/') === 0) {
    $filePath = __DIR__ . '/swagger-ui/' . substr($requestUri, strlen('/docs/'));
    if (file_exists($filePath) && !is_dir($filePath)) {
        $mimeType = mime_content_type($filePath);
        header('Content-Type: ' . $mimeType);
        readfile($filePath);
        exit();
    }
} elseif ($requestUri === '/openapi.json') {
    header('Content-Type: application/json');
    readfile(__DIR__ . '/openapi.json');
    exit();
}

// Fallback for your actual API endpoints or other routes
// echo "Welcome to your API";
?>

# Example of a simple Nginx configuration snippet for Swagger UI
# location /docs {
#     alias /path/to/your/project/public/swagger-ui/;
#     index index.html;
#     try_files $uri $uri/ =404;
# }
#
# location /openapi.json {
#     alias /path/to/your/project/public/openapi.json;
# }