OpenAPI Overview
OpenAPI support is metadata-driven. Since v0.2.0 it includes security scheme support and pre-built WooCommerce domain schemas.
Release 1.1.2
The exporter now has external OpenAPI 3.1 document validation and native WP/Woo wire-schema checks in CI. It rejects duplicate operations/IDs and ambiguous templates, validates security requirements/scheme names and checks nested local references in strict mode. Empty schema maps and empty paths serialize as objects. PUT and PATCH operation IDs are distinct.
Applications still supply custom schemas and real authentication declarations. Runtime checks do not fetch external references or resolve anchors; validate the final application document with a full validator. Arbitrary PHP inference and advanced generation are outside the exporter scope. Analytics helpers cover all twelve reports.
What is available
- contract aggregation from Router/Resource
- OpenAPI 3.1.0 document export
- optional runtime endpoint:
/openapi.json
Metadata fields used
operationIdtagsscopesparametersrequestSchemaresponseSchemaresponsesopenapi.include
openapi.include=false routes are excluded by default.
What is not available yet
- full automatic schema inference from arbitrary PHP runtime types
- advanced polymorphism/discriminator generation
What is new in v1.1.0
- Executable route
argsare exported automatically aspath/queryparameters (type,default,enum,format,minimum/maximum,minLength/maxLength,pattern, anddescriptionare carried over). List filters and pagination params no longer need a duplicatemeta.parametersdeclaration. - Explicit
meta.parametersentries override a derived parameter with the samenameandinlocation; derived parameters without an explicit counterpart are kept. OPTIONSoperations are documented with a204success response (no content).- Custom
meta.responsesentries now replace the generated defaults for the same status code (previously the defaults won), so a route can override the success response or thedefaulterror reference.
What is new in v0.2.0
- Security scheme support: Bearer, Basic Auth, API Key, OAuth2, Cookie
- Global and per-route security requirements
- Pre-built WooCommerce domain schemas via
BetterRoute::wooOpenApiComponents()(see WooCommerce > OpenAPI Components)
What is new in v0.4.0
- Per-operation
security: []overridesglobalSecurity. Settingsecurityto an empty array on an operation drops it from the document's global security requirement (useful for public health checks, webhooks, or auth endpoints inside an otherwise authenticated API). RouteBuilder::publicRoute()automatically writessecurity: []to the operation meta, so a route that opts out of WP auth also opts out of OpenAPI's global security.RouteBuilder::protectedByMiddleware($security)propagates the supplied security scheme (string or array) into the operation meta when present.
What is new in v0.3.0
strictSchemas => trueexporter option — throwsInvalidArgumentExceptionon$refto an unknown component instead of substituting a permissive placeholderOpenApiRouteRegistrar::register()defaults tocurrent_user_can('manage_options')— passpermissionCallbackto override
Validation checklist
- every documented endpoint has stable
operationId - schemas referenced by
$refexist in components - intentionally internal routes set
openapi.include=false