APPNETOS is under active development This website and its documentation are being prepared for public launch. Content and features may change.
Select Theme
Loading

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.

OpenAPI command activates a REST context, discovers Collections, builds schemas and writes context-specific JSON files
Generation is isolated by application and REST context.

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.

Next Steps

Previous

Security & CORS

Explore Security & CORS

Next

Swagger UI

Explore Swagger UI