br-openapi

better-route: OpenAPI 3.1

Export collected contracts directly or publish a protected REST document endpoint.

Export

use BetterRoute\BetterRoute;

$contracts = array_merge(
    $router->contracts(openApiOnly: true),
    $resource->contracts(openApiOnly: true),
);

$document = BetterRoute::openApiExporter()->export($contracts, [
    'title' => 'My API',
    'version' => 'v1.1.0',
    'serverUrl' => '/wp-json',
    'strictSchemas' => true,
    'components' => [
        'schemas' => [/* application schemas */],
    ],
]);

Contracts exist after route declarations for a Router and after register() for a Resource/Woo registrar result.

Publish openapi.json

use BetterRoute\OpenApi\OpenApiRouteRegistrar;

OpenApiRouteRegistrar::register(
    restNamespace: 'myapp/v1',
    contractsProvider: static fn (): array => OpenApiRouteRegistrar::contractsFromSources([
        $router,
        $resource,
        $woo,
    ]),
    options: [
        'title' => 'My API',
        'version' => 'v1.1.0',
        // Omit to keep the manage_options default.
        'permissionCallback' => static fn (): bool => current_user_can('view_api_docs'),
    ],
);

The registrar mounts GET /wp-json/myapp/v1/openapi.json. Its default permission is current_user_can('manage_options'). Make it public only deliberately:

'permissionCallback' => static fn (): bool => true,

The provider must be callable and return a contract list. contractsFromSources() accepts a mixed list of Router instances, Resource instances, and contract lists and filters each source with openApiOnly: true by default.

Route inclusion

Exclude a route with the actual metadata shape:

$router->get('/internal', $handler)
    ->permission($adminPermission)
    ->meta(['openapi' => ['include' => false]]);

Then use contracts(true) or the exporter's default includeExcluded: false. The obsolete meta(['openApiOnly' => false]) shape does not control inclusion.

1.1 parameter derivation