OpenAPI Generator
Generate accurate API contracts directly from APPNETOS REST Collections.
Turn annotated Collections and typed Documents into context-specific OpenAPI 3.1 definitions without maintaining separate endpoint specifications.
Generation workflow
The OpenAPI generator discovers registered REST Collections for the active application and REST context. It converts resource metadata into an OpenAPI 3.1 definition, generates Document schemas through reflection, and persists the definition and metadata to the application runtime directory.
The command rebuilds the active runtime, class mappings, REST registry and OpenAPI services between contexts to prevent resource or schema leakage.
CLI command
Run the generator from the APPNETOS project root. The application name is required; the REST context is optional.
php bin/appnetos cmd appnetos:openapi:generate my-application
php bin/appnetos cmd appnetos:openapi:generate my-application rest
php bin/appnetos cmd appnetos:openapi:generate my-application admin-rest
Without a context argument, the command processes the REST contexts configured for the application.
Explicit context arguments are limited to rest and admin-rest. The alias
openapi:generate is also registered. An application must exist and declare the
requested
REST context.
Resource discovery and operations
The generator initializes Core\Rest\Registry and reads its registered resources. REST
Collection annotations define which resources and HTTP methods are exposed. For each resource, the
generator builds paths, operation identifiers, summaries, request bodies, parameters, response
definitions and reusable components.
The generated definition contains openapi, info, servers,
security,
tags, paths and components.
Document schemas and validation
Core\Rest\OpenApi\Schema reflects Document properties, including inherited properties,
PHP
types, nullability, defaults and validation annotations. The schema generator distinguishes read and
write modes and determines required properties where applicable.
If a Document class cannot be resolved or reflected, the generator uses a permissive fallback schema. This allows generation to continue, but such schemas should be investigated before publishing an API contract.
Servers, security and context isolation
Server URLs are derived from the active application's route configuration. Configured hosts are preferred; a context slug can be used as a fallback. Protocol-less host entries are supported for deployments behind reverse proxies.
Security definitions are resolved from the application's context-specific security configuration.
Generating both rest and admin-rest produces separate API definitions, not
a
merged specification.
Generated files
Core\Rest\OpenApi\Writer writes pretty-printed JSON to the following application- and
context-specific location:
custom/<application>/.files/OpenAPI/<context>/
├── rest.json
└── metadata.json
rest.json contains the OpenAPI definition. metadata.json records the
application, context, generation timestamp, generator identifier and version. Regeneration writes
the
files again for the selected context.
Public API Reference
Core\Rest\OpenApi\Generator
Class & Registry
Class:
Core\Rest\OpenApi\Generator
Extends:
Core\Rest\OpenApi\Generator\Base
use Core\Rest\OpenApi\Generator;
use Core\Registry;
$generator = Registry::get(Generator::class);
| Method | Description |
|---|---|
Core\Rest\OpenApi\Base::__construct() |
Construct the OpenAPI orchestration service. |
Core\Rest\OpenApi\Base::generate(): bool |
Generate the definition and delegate persistence to the writer. |
Core\Rest\OpenApi\Generator\Base::__construct() |
Construct the definition generator. |
Core\Rest\OpenApi\Generator\Base::generate(): array |
Build the OpenAPI definition from registered resources. |
Core\Rest\OpenApi\Schema\Base::__construct() |
Construct the Document schema generator. |
Core\Rest\OpenApi\Schema\Base::generate(string $document, string $mode =
'read',
string|null $title = null): array |
Build a Document schema for the selected mode. |
Core\Rest\OpenApi\Writer\Base::__construct() |
Construct the runtime file writer. |
Core\Rest\OpenApi\Writer\Base::write(array $definition): bool |
Write the definition and metadata JSON files. |
Core\Rest\OpenApi\Writer\Base::getFilename(): string |
Return the OpenAPI definition filename. |
Core\Rest\OpenApi\Writer\Base::getMetadataFilename(): string |
Return the metadata filename. |
Core\Cmd\Command\OpenApiGenerate::__construct() |
Construct the CLI command. |
Core\Cmd\Command\OpenApiGenerate::execute(Input $input, Output $output):
int
|
Validate arguments and generate one or all configured REST contexts. |