Export collected contracts directly or publish a protected REST document endpoint.
\nuse BetterRoute\\BetterRoute;\n\n$contracts = array_merge(\n $router->contracts(openApiOnly: true),\n $resource->contracts(openApiOnly: true),\n);\n\n$document = BetterRoute::openApiExporter()->export($contracts, [\n 'title' => 'My API',\n 'version' => 'v1.1.0',\n 'serverUrl' => '/wp-json',\n 'strictSchemas' => true,\n 'components' => [\n 'schemas' => [/* application schemas */],\n ],\n]);\nContracts exist after route declarations for a Router and after register() for a Resource/Woo registrar result.
use BetterRoute\\OpenApi\\OpenApiRouteRegistrar;\n\nOpenApiRouteRegistrar::register(\n restNamespace: 'myapp/v1',\n contractsProvider: static fn (): array => OpenApiRouteRegistrar::contractsFromSources([\n $router,\n $resource,\n $woo,\n ]),\n options: [\n 'title' => 'My API',\n 'version' => 'v1.1.0',\n // Omit to keep the manage_options default.\n 'permissionCallback' => static fn (): bool => current_user_can('view_api_docs'),\n ],\n);\nThe 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,\nThe 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.
Exclude a route with the actual metadata shape:
\n$router->get('/internal', $handler)\n ->permission($adminPermission)\n ->meta(['openapi' => ['include' => false]]);\nThen use contracts(true) or the exporter's default includeExcluded: false. The obsolete meta(['openApiOnly' => false]) shape does not control inclusion.
Executable WordPress route args automatically become OpenAPI path/query parameters:
$router->get('/articles/(?P<id>\\d+)', $handler)\n ->publicRoute()\n ->args([\n 'id' => ['type' => 'integer', 'required' => true],\n 'context' => ['type' => 'string', 'enum' => ['view', 'edit']],\n ]);\nThe exporter renders the path as /myapp/v1/articles/{id}, puts id in path, and context in query. It carries supported schema keys such as enum/default/format/items/min/max/length/pattern.
Explicit meta.parameters entries override a derived entry with the same case-insensitive in + name; derived parameters not overridden remain present. Use explicit metadata for headers/cookies or richer descriptions, not to duplicate every args rule.
Defaults are:
\n201;204 with no JSON body;200;default: ErrorResponse.An explicit meta.responses[status] replaces the default at that same status:
->meta([\n 'responses' => [\n '202' => ['description' => 'Accepted'],\n 'default' => ['$ref' => '#/components/responses/ErrorResponse'],\n ],\n])\nHEAD and 204 responses are emitted without content.
Resource create/update responses are {data: ...} and must reference <Resource>Response. A get references <Resource> unless uniformEnvelope(true) is enabled, in which case it also references <Resource>Response. Lists use <Resource>ListResponse.
In strict mode provide, as applicable:
\n<Resource><Resource>Input<Resource>Response<Resource>ListResponseDeleteResponseDeclare schemes and document defaults explicitly:
\n'securitySchemes' => [\n 'bearerAuth' => [\n 'type' => 'http',\n 'scheme' => 'bearer',\n 'bearerFormat' => 'JWT',\n ],\n],\n'globalSecurity' => [['bearerAuth' => []]],\npublicRoute() and explicitly public Resource actions emit operation security: []. protectedByMiddleware('bearerAuth') or a list of security objects sets route metadata. Better Route does not infer a scheme definition from middleware; the component must still be supplied.
strictSchemas: true throws when a referenced #/components/schemas/... is absent. Default false inserts a permissive object schema for compatibility. Prefer strict mode for a controlled API contract.
Merge components recursively so Woo and application schema maps do not overwrite one another:
\n'components' => array_replace_recursive(\n BetterRoute::wooOpenApiComponents(),\n $applicationComponents,\n),\nWoo 1.1 components match runtime strict payloads: money is string-typed, product input excludes derived price, customer create requires email, coupon create requires code, and nested objects reject unknown properties where runtime does.
openapi.include, not openApiOnly metadata.args; override rather than duplicate.br-routes for args, intent, and route metadata.br-resource-cpt/br-resource-table for Resource response shapes.br-woo-routes for Woo runtime contracts.src/OpenApi/OpenApiExporter.phpsrc/OpenApi/OpenApiRouteRegistrar.phpsrc/Router/Router.phpsrc/Resource/Resource.phpsrc/Integration/Woo/WooOpenApiComponents.php