<?php

declare(strict_types=1);

namespace App\Http\Controllers;

use Illuminate\Contracts\View\View;
use Illuminate\Http\Request;
use Symfony\Component\HttpKernel\Exception\NotFoundHttpException;

/**
 * Browsable documentation for both APIs.
 *
 * The specification itself has always been there, as a file
 * ([`public/openapi.yaml`](public/openapi.yaml)); what was missing was
 * somewhere to read it. The people who need it most write the public frontend
 * and have no reason to hold a panel account, so this is readable without
 * signing in — the specification describes endpoints, not secrets, and it was
 * already served at a fixed public path.
 */
class DocsController extends Controller
{
    public function __invoke(Request $request): View
    {
        if (! file_exists(public_path('openapi.yaml'))) {
            throw new NotFoundHttpException('The API specification has not been published.');
        }

        return view('docs.api', [
            'spec' => asset('openapi.yaml'),

            // Beside the specification because it is the same contract, and
            // whoever is here is the person who needs it: generated with
            // `php artisan api:types`, absent if it was never generated.
            'types' => file_exists(public_path('api-types.d.ts')) ? asset('api-types.d.ts') : null,

            // "Try it out" must call the installation you are actually
            // looking at, not the canonical one in the configuration — the
            // same page is opened on a laptop, on staging and in production.
            'apiBase' => url('/api'),

            'server' => $request->getHost(),
            'environment' => (string) config('app.env'),
        ]);
    }
}