water/server/scripts/build_mini_docs.php

<?php

declare(strict_types=1);

/** Publish the canonical OpenAPI file for the static documentation page. No application bootstrap or database access. */
$root = dirname(__DIR__);
$source = $root . '/docs/openapi/water-mini-v1.json';
$target = $root . '/public/docs/mini/openapi.json';
$content = file_get_contents($source);
if ($content === false) {
    throw new RuntimeException('Cannot read the canonical OpenAPI file.');
}
$specification = json_decode($content, true, 512, JSON_THROW_ON_ERROR);
if (($specification['openapi'] ?? '') !== '3.0.3' || empty($specification['paths'])) {
    throw new RuntimeException('Invalid mini API specification.');
}
if (in_array('--check', $argv, true)) {
    if (!is_file($target) || file_get_contents($target) !== $content) {
        fwrite(STDERR, "Published OpenAPI is stale. Run: php scripts/build_mini_docs.php\n");
        exit(1);
    }
    echo "Published OpenAPI matches the canonical file.\n";
    exit;
}
if (file_put_contents($target, $content, LOCK_EX) !== strlen($content)) {
    throw new RuntimeException('Cannot publish OpenAPI.');
}
echo "Published: /docs/mini/index.html (OpenAPI synchronized).\n";