PHP code example of tsitsishvili / documentator

    
        
<?php
require_once('vendor/autoload.php');

/* Start to develop here. Best regards https://php-download.com/ */

    

tsitsishvili / documentator example snippets

/**
 * Create an order.
 *
 * Charges the customer and returns the created order. This summary and
 * description are read straight from the docblock — no attributes needed.
 */
public function store(StoreOrderRequest $request): OrderResource
{
    // Inferred with no attributes: path param {order}, body params from
    // StoreOrderRequest::rules(), a 201 response from OrderResource.
    return new OrderResource(Order::create($request->validated()));
}

public function store(CreateOrderData $data): OrderData
{
    // body params from CreateOrderData's typed properties; 201 response from OrderData
    return OrderData::from(Order::create($data->toArray()));
}

use Tsitsishvili\Documentator\Attributes\{Summary, Description, Group, BodyParam, HeaderParam, CookieParam, Response, ResponseHeader, RequestMediaType, OperationId, Server, Authenticated};

#[Group('Orders')]
#[OperationId('createOrder')]
#[Server('https://tenant.example.com', description: 'Tenant API')]
#[Summary('Create an order')]
#[Description('Creates an order for the authenticated customer.')]
#[Authenticated]
#[HeaderParam('X-Tenant', errors: array<string, list<string>>}')]
public function store(StoreOrderRequest $request): OrderResource
{
    // ...
}

#[Group('Products', version: 'v2')]
final class ProductController
{
    // ...
}

$request->validate([
    /**
     * Literal API key. The escaped dot stays part of the field name.
     *
     * @var uuid
     * @example 9f40d932-c4c0-4a36-9fb5-10d18c2a1f61
     * @default 9f40d932-c4c0-4a36-9fb5-10d18c2a1f61
     */
    'user\.uuid' => ['

'routes' => [
    'match' => ['api/*', 'app/*'],
],

'grouping' => [
    'sections' => [
        'api' => 'API',
        'app' => 'App',
    ],
],

'grouping' => [
    'source' => 'auto', // auto, controller, path
    'path_depth' => 1,
    'ignore_path_prefixes' => ['api'],
    'ignore_path_parameters' => true,
],

'global_path_parameters' => [
    'pathlang' => [
        'description' => 'Language code used by localized routes.',
        'schema' => ['type' => 'string', 'enum' => ['ka', 'en']],
        'example' => 'ka',
        'grouping' => false,
    ],
],

use Tsitsishvili\Documentator\Documentator;

Documentator::auth(fn ($request) => $request->user()?->is_admin);

bash
php artisan vendor:publish --tag=documentator-config

bash
php artisan documentator:generate                  # warm the cache (set DOCUMENTATOR_CACHE=true)
php artisan documentator:export openapi.json        # write the OpenAPI spec for CI / tooling
php artisan documentator:postman collection.json    # export a Postman v2.1 collection

bash
php artisan documentator:check                         # report issues (exit 0)
php artisan documentator:check --strict                # fail the build if any issue is found
php artisan documentator:check --json                  # machine-readable CI/dashboard payload
php artisan documentator:check --suggest-hidden        # suggest internal/debug routes to hide
php artisan documentator:check --against=openapi.json  # fail if the spec has drifted; re-export and commit