OpenAPI Exporter
BetterRoute\OpenApi\OpenApiExporter::export(array $contracts, array $options = []): array
Minimal example
use BetterRoute\OpenApi\OpenApiExporter;
$contracts = array_merge(
$router->contracts(true),
$resource->contracts(true)
);
$document = (new OpenApiExporter())->export($contracts, [
'title' => 'better-route API',
'version' => 'v1.1.0',
'description' => 'Contract-first API',
'serverUrl' => '/wp-json',
'openapiVersion' => '3.1.0',
'strictSchemas' => true, // v0.3.0; throws on unknown $ref components
'components' => [
'schemas' => [
'Article' => ['type' => 'object'],
],
],
]);
Export options
titleversiondescriptionserverUrlopenapiVersionincludeExcludedcomponentsstrictSchemas(v0.3.0) — whentrue, missing component references throwInvalidArgumentExceptioninstead of being substituted with{ type: 'object', additionalProperties: true }
Important behavior
Since 1.1.2:
- Duplicate method/path, equivalent templates with different parameter names and duplicate operation IDs throw. PUT keeps Update; PATCH uses Patch. Woo operationIdPrefix supports multiple registrations.
- Balanced named captures become path parameters; unsupported regex outside captures fails. Escape literal dots in WordPress route patterns. Exclude unrepresentable PCRE routes.
- Query/path/cookie names are case-sensitive; headers merge case-insensitively. Explicit parameters preserve style/explode/allowReserved/examples. WP boolean exclusive bounds convert recursively into numeric JSON Schema bounds. Custom schemas use 2020-12 syntax.
- summary, description and deprecated are standard operation fields. Inline HEAD/204/304 responses omit content. Referenced response definitions remain application-owned.
- Strict mode follows nested local JSON pointers, not just top-level schema names. Default compatibility mode only fills missing direct schema references with placeholders. External references/anchors are not resolved; full validation remains required.
- Malformed security requirements and undefined schemes throw. Omission inherits global
security;
[]makes an operation public,[{}]adds an anonymous alternative. Local scheme aliases resolve and non-OAuth role arrays are legal in OpenAPI 3.1. Metadata enforces no auth.
Validate serialized output, including the application's custom components:
php tests/openapi/export.php /tmp/better-route-openapi.json
python -m pip install -r tests/openapi/requirements.txt
python tests/openapi/validate.py /tmp/better-route-openapi.json
The library's CI validates four document variants and native synthetic WP/Woo responses; it does not prove arbitrary consumer schemas or handlers. Version 2.0 requires PHP 8.3; the 1.1.2 release retains PHP 8.1 compatibility.
- Path regex placeholders
(?P<id>...)convert to{id} - Path params are forced
required=true - Unsupported HTTP methods are skipped
defaultresponse references#/components/responses/ErrorResponse- (v1.1.0) Executable route
argsare exported aspath/queryparameters automatically; explicitmeta.parametersentries override derived ones with the samename+in - (v1.1.0)
OPTIONSoperations emit a204success response without content;HEADresponses carry no content schema - (v1.1.0) Custom
meta.responsesreplace the generated default for the same status code (previously the default won)
Common mistakes
- forgetting
openapi.include=falsefor internal ops - using invalid
parametersstructure - referencing non-existent schemas
Validation checklist
- generated document has
openapi,info,servers,paths,components - expected operations include
x-scopesandx-better-routeextensions - POST routes emit
201success response