@omnifyjp/omnify 3.5.0 → 3.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@omnifyjp/omnify",
-  "version": "3.5.0",
+  "version": "3.7.0",
   "description": "Schema-driven code generation for Laravel, TypeScript, and SQL",
   "license": "MIT",
   "repository": {
@@ -36,10 +36,10 @@
     "zod": "^3.24.0"
   },
   "optionalDependencies": {
-    "@omnifyjp/omnify-darwin-arm64": "3.5.0",
-    "@omnifyjp/omnify-darwin-x64": "3.5.0",
-    "@omnifyjp/omnify-linux-x64": "3.5.0",
-    "@omnifyjp/omnify-linux-arm64": "3.5.0",
-    "@omnifyjp/omnify-win32-x64": "3.5.0"
+    "@omnifyjp/omnify-darwin-arm64": "3.7.0",
+    "@omnifyjp/omnify-darwin-x64": "3.7.0",
+    "@omnifyjp/omnify-linux-x64": "3.7.0",
+    "@omnifyjp/omnify-linux-arm64": "3.7.0",
+    "@omnifyjp/omnify-win32-x64": "3.7.0"
   }
 }

package/ts-dist/php/controller-generator.js

@@ -3,6 +3,7 @@
  */
 import { toPascalCase } from './naming-helper.js';
 import { baseFile, userFile, resolveModularBasePath, resolveModularBaseNamespace } from './types.js';
+import { buildControllerMethodAttributes, openApiControllerImports } from './openapi-generator.js';
 const DEFAULT_ACTIONS = ['index', 'store', 'show', 'update', 'destroy'];
 /** Generate controller classes for all schemas with api config. */
 export function generateControllers(reader, config) {
@@ -50,10 +51,21 @@ function generateBaseController(name, schema, reader, config) {
     if (actions.includes('index') || lookup) {
         imports.push(`use Illuminate\\Http\\Resources\\Json\\AnonymousResourceCollection;`);
     }
+    // Issue #35: opt-in `use OpenApi\Attributes as OA;` so the inline `#[OA\...]`
+    // attributes resolve when openapi codegen is enabled.
+    imports.push(...openApiControllerImports(config));
+    // Issue #35: build the per-method `#[OA\...]` attribute block once and
+    // splice it in front of each method body. The helper returns an empty
+    // array when openapi codegen is disabled, so the rendered template stays
+    // byte-identical for projects that don't opt in.
+    const attrFor = (m) => {
+        const lines = buildControllerMethodAttributes(config, schema, modelName, name, m);
+        return lines.length === 0 ? '' : '\n    ' + lines.join('\n    ');
+    };
     // Build methods
     const methods = [];
     if (actions.includes('index')) {
-        methods.push(`
+        methods.push(`${attrFor('index')}
     public function index(Request $request): AnonymousResourceCollection
     {
         $result = $this->service->list($request->all());
@@ -62,7 +74,7 @@ function generateBaseController(name, schema, reader, config) {
     }`);
     }
     if (actions.includes('store')) {
-        methods.push(`
+        methods.push(`${attrFor('store')}
     public function store(${modelName}StoreRequest $request): JsonResponse
     {
         $model = $this->service->create($request->validated());
@@ -73,14 +85,14 @@ function generateBaseController(name, schema, reader, config) {
     }`);
     }
     if (actions.includes('show')) {
-        methods.push(`
+        methods.push(`${attrFor('show')}
     public function show(${modelName} $model): ${modelName}Resource
     {
         return new ${modelName}Resource($model);
     }`);
     }
     if (actions.includes('update')) {
-        methods.push(`
+        methods.push(`${attrFor('update')}
     public function update(${modelName}UpdateRequest $request, ${modelName} $model): ${modelName}Resource
     {
         $model = $this->service->update($model, $request->validated());
@@ -89,7 +101,7 @@ function generateBaseController(name, schema, reader, config) {
     }`);
     }
     if (actions.includes('destroy')) {
-        methods.push(`
+        methods.push(`${attrFor('destroy')}
     public function destroy(${modelName} $model): JsonResponse
     {
         $this->service->delete($model);
@@ -98,7 +110,7 @@ function generateBaseController(name, schema, reader, config) {
     }`);
     }
     if (lookup) {
-        methods.push(`
+        methods.push(`${attrFor('lookup')}
     public function lookup(Request $request): AnonymousResourceCollection
     {
         $result = $this->service->lookup($request->all());
@@ -107,7 +119,7 @@ function generateBaseController(name, schema, reader, config) {
     }`);
     }
     if (bulkDelete) {
-        methods.push(`
+        methods.push(`${attrFor('bulkDelete')}
     public function bulkDelete(Request $request): JsonResponse
     {
         $this->service->bulkDelete($request->input('ids', []));
@@ -116,7 +128,7 @@ function generateBaseController(name, schema, reader, config) {
     }`);
     }
     if (restore) {
-        methods.push(`
+        methods.push(`${attrFor('restore')}
     public function restore(string $id): ${modelName}Resource
     {
         $model = $this->service->restore($id);

package/ts-dist/php/enum-generator.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Generates PHP enum classes for `kind: enum` schemas.
+ *
+ * Issue #34: every enum schema becomes a self-contained PHP 8.1+ backed enum
+ * placed in the global Omnify enums namespace (default `App\Omnify\Enums`).
+ * Localized labels from the schema are embedded as a `LABELS` constant so
+ * the generated enum is usable without setting up Laravel translation files.
+ *
+ * Class name convention: `{SchemaName}Enum.php` (e.g. schema `MenuStatus` →
+ * `MenuStatusEnum`). The trailing `Enum` suffix is intentional — it prevents
+ * collisions with model classes of the same base name and signals "this is an
+ * enum class" at every callsite (`MenuStatusEnum::Draft`).
+ */
+import { SchemaReader } from './schema-reader.js';
+import type { GeneratedFile, PhpConfig } from './types.js';
+/** Generate one PHP enum class for each `kind: enum` schema. */
+export declare function generateEnums(reader: SchemaReader, config: PhpConfig): GeneratedFile[];
+/** Convert a schema name (e.g. `MenuStatus`) to its enum class name (`MenuStatusEnum`). */
+export declare function enumClassName(schemaName: string): string;

package/ts-dist/php/enum-generator.js

@@ -0,0 +1,165 @@
+/**
+ * Generates PHP enum classes for `kind: enum` schemas.
+ *
+ * Issue #34: every enum schema becomes a self-contained PHP 8.1+ backed enum
+ * placed in the global Omnify enums namespace (default `App\Omnify\Enums`).
+ * Localized labels from the schema are embedded as a `LABELS` constant so
+ * the generated enum is usable without setting up Laravel translation files.
+ *
+ * Class name convention: `{SchemaName}Enum.php` (e.g. schema `MenuStatus` →
+ * `MenuStatusEnum`). The trailing `Enum` suffix is intentional — it prevents
+ * collisions with model classes of the same base name and signals "this is an
+ * enum class" at every callsite (`MenuStatusEnum::Draft`).
+ */
+import { toPascalCase } from './naming-helper.js';
+import { baseFile, resolveGlobalEnumPath, resolveGlobalEnumNamespace } from './types.js';
+/** Generate one PHP enum class for each `kind: enum` schema. */
+export function generateEnums(reader, config) {
+    const files = [];
+    for (const [name, schema] of Object.entries(reader.getEnumSchemas())) {
+        // Skip package-owned enums — those are generated by their owning package's
+        // codegen, not the host project's. Mirrors how object schemas are filtered
+        // by `getProjectObjectSchemas()` elsewhere.
+        if (schema.package != null)
+            continue;
+        files.push(generateEnumClass(name, schema, config));
+    }
+    return files;
+}
+function generateEnumClass(name, schema, config) {
+    const className = enumClassName(name);
+    const namespace = resolveGlobalEnumNamespace(config, config.models.namespace);
+    const values = (schema.values ?? []);
+    const cases = values.map(v => buildCase(v));
+    const labelsConst = buildLabelsConstant(values);
+    const content = `<?php
+
+namespace ${namespace};
+
+/**
+ * ${name}${schema.displayName ? ` — ${pickDefaultLabel(schema.displayName)}` : ''}
+ *
+ * DO NOT EDIT - This file is auto-generated by Omnify.
+ * Any changes will be overwritten on next generation.
+ *
+ * @generated by omnify
+ */
+enum ${className}: string
+{
+${cases.map(c => `    ${c}`).join('\n')}
+
+${labelsConst}
+
+    /**
+     * Get the localized label for this enum case.
+     *
+     * Falls back to the configured app fallback locale, then any defined
+     * locale, then the raw value if no labels were declared in the schema.
+     */
+    public function label(?string $locale = null): string
+    {
+        $locale = $locale ?? app()->getLocale();
+        $labels = static::LABELS[$this->value] ?? [];
+
+        return $labels[$locale]
+            ?? $labels[config('app.fallback_locale', 'en')]
+            ?? $labels[array_key_first($labels) ?? 'en']
+            ?? $this->value;
+    }
+
+    /**
+     * Get all enum values as a flat list.
+     *
+     * @return array<int, string>
+     */
+    public static function values(): array
+    {
+        return array_column(self::cases(), 'value');
+    }
+
+    /**
+     * Get an array of value → localized label suitable for select dropdowns.
+     *
+     * @return array<string, string>
+     */
+    public static function options(?string $locale = null): array
+    {
+        $out = [];
+        foreach (self::cases() as $case) {
+            $out[$case->value] = $case->label($locale);
+        }
+        return $out;
+    }
+}
+`;
+    return baseFile(resolveGlobalEnumPath(config, `${className}.php`, config.models.path), content);
+}
+/** Convert a schema name (e.g. `MenuStatus`) to its enum class name (`MenuStatusEnum`). */
+export function enumClassName(schemaName) {
+    const pascal = toPascalCase(schemaName);
+    return pascal.endsWith('Enum') ? pascal : `${pascal}Enum`;
+}
+/** Build a single `case Foo = 'foo';` line from a schema enum value. */
+function buildCase(v) {
+    const value = v.value;
+    return `case ${toPhpCaseName(value)} = '${escapePhpString(value)}';`;
+}
+/**
+ * Convert an enum value into a valid PHP case identifier. PHP case names must
+ * start with a letter or underscore and contain only `[A-Za-z0-9_]`. We map
+ * everything else through PascalCase and prefix a digit-leading name with
+ * `Case` so it's still legal.
+ */
+function toPhpCaseName(value) {
+    const cleaned = value
+        .replace(/[^A-Za-z0-9_]+/g, '_')
+        .split('_')
+        .filter(Boolean)
+        .map(part => part.charAt(0).toUpperCase() + part.slice(1))
+        .join('');
+    if (!cleaned)
+        return 'Unknown';
+    return /^[0-9]/.test(cleaned) ? `Case${cleaned}` : cleaned;
+}
+/** Build the `LABELS` constant containing every locale label for every value. */
+function buildLabelsConstant(values) {
+    const lines = [];
+    lines.push('    /**');
+    lines.push('     * Localized labels for each case, embedded directly so the generated enum');
+    lines.push('     * is self-contained and works without Laravel translation files.');
+    lines.push('     *');
+    lines.push('     * @var array<string, array<string, string>>');
+    lines.push('     */');
+    lines.push('    public const LABELS = [');
+    for (const v of values) {
+        const rawLabel = v.label;
+        // `label` can be either a plain string or a `{locale: text}` map. Normalize.
+        const labels = typeof rawLabel === 'string'
+            ? { en: rawLabel }
+            : (rawLabel ?? {});
+        const entries = Object.entries(labels);
+        if (entries.length === 0) {
+            lines.push(`        '${escapePhpString(v.value)}' => [],`);
+            continue;
+        }
+        const inner = entries
+            .map(([loc, txt]) => `'${escapePhpString(loc)}' => '${escapePhpString(String(txt))}'`)
+            .join(', ');
+        lines.push(`        '${escapePhpString(v.value)}' => [${inner}],`);
+    }
+    lines.push('    ];');
+    return lines.join('\n');
+}
+/** Pick a sensible default label from a localized string for the doc comment. */
+function pickDefaultLabel(displayName) {
+    if (typeof displayName === 'string')
+        return displayName;
+    return (displayName.en ??
+        displayName.ja ??
+        Object.values(displayName)[0] ??
+        '');
+}
+/** Escape single quotes and backslashes for inclusion in a PHP single-quoted string. */
+function escapePhpString(value) {
+    return value.replace(/\\/g, '\\\\').replace(/'/g, "\\'");
+}

package/ts-dist/php/index.js

@@ -30,6 +30,8 @@ import { baseFile } from './types.js';
 import { generateControllers } from './controller-generator.js';
 import { generateServices } from './service-generator.js';
 import { generateRoutes } from './route-generator.js';
+import { generateEnums } from './enum-generator.js';
+import { generateOpenApi } from './openapi-generator.js';
 export { derivePhpConfig } from './types.js';
 /** Generate all PHP files from schemas.json data. */
 export function generatePhp(data, overrides) {
@@ -60,7 +62,14 @@ export function generatePhp(data, overrides) {
         files.push(...generateControllers(reader, config));
         files.push(...generateServices(reader, config));
         files.push(...generateRoutes(reader, config));
+        // Issue #35: opt-in OpenAPI / Swagger annotation scaffold.
+        // Controller-level method attributes are emitted inline by
+        // `generateControllers` above when `config.openapi.enable` is true; here
+        // we add the standalone Common / Info / Schemas files.
+        files.push(...generateOpenApi(reader, config));
     }
+    // Issue #34: every `kind: enum` schema becomes a global PHP enum class.
+    files.push(...generateEnums(reader, config));
     // Per-schema files
     files.push(...generateLocales(reader, config));
     files.push(...generateModels(reader, config));

package/ts-dist/php/model-generator.js

@@ -4,7 +4,8 @@
 import { toPascalCase, toSnakeCase, toCamelCase } from './naming-helper.js';
 import { toCast, toPhpDocType, isHiddenByDefault } from './type-mapper.js';
 import { buildRelation } from './relation-builder.js';
-import { baseFile, userFile, resolveModularBasePath, resolveModularBaseNamespace, resolveSharedBaseNamespace, resolveGlobalTraitNamespace, } from './types.js';
+import { baseFile, userFile, resolveModularBasePath, resolveModularBaseNamespace, resolveSharedBaseNamespace, resolveGlobalTraitNamespace, resolveGlobalEnumNamespace, } from './types.js';
+import { enumClassName } from './enum-generator.js';
 /** Generate base model and user model for all project-owned object schemas,
  *  plus user models for package schemas (extending the package model). */
 export function generateModels(reader, config) {
@@ -71,7 +72,7 @@ function generateBaseModel(name, schema, reader, config) {
     const fillable = buildFillable(properties, expandedProperties, propertyOrder);
     const hidden = buildHidden(properties, expandedProperties, propertyOrder);
     const appends = buildAppends(expandedProperties);
-    const casts = buildCasts(properties, expandedProperties, propertyOrder, reader);
+    const casts = buildCasts(properties, expandedProperties, propertyOrder, reader, config);
     const relations = buildRelations(name, properties, propertyOrder, modelNamespace, reader);
     const accessors = buildAccessors(expandedProperties);
     const fileAccessors = hasFiles ? buildFileAccessors(properties, propertyOrder, modelNamespace) : '';
@@ -253,9 +254,14 @@ function buildImports(baseNamespace, modelName, hasSoftDelete, isAuthenticatable
     lines.push(`use ${traitsNamespace || baseNamespace + '\\Traits'}\\HasLocalizedDisplayName;`);
     lines.push(`use ${localesNamespace || baseNamespace + '\\Locales'}\\${modelName}Locales;`);
     if (hasFiles) {
-        // HasFiles lives in File module, not Shared
+        // Issue #33 followup: HasFiles is a global Omnify trait — see
+        // file-trait-generator.ts. The trait now lives at
+        // `app/Omnify/Traits/HasFiles.php` (namespace `App\Omnify\Traits`),
+        // not under per-module `Modules/File/Traits/`. The import statement
+        // here must match, otherwise generated models crash with
+        // `Trait "App\Omnify\Modules\File\Traits\HasFiles" not found`.
         const fileTraitsNs = config
-            ? resolveModularBaseNamespace(config, 'File', 'Traits', baseNamespace + '\\Traits')
+            ? resolveGlobalTraitNamespace(config, baseNamespace + '\\Traits')
             : (traitsNamespace || baseNamespace + '\\Traits');
         lines.push(`use ${fileTraitsNs}\\HasFiles;`);
         if (modelNamespace) {
@@ -423,13 +429,29 @@ function buildAppends(expandedProperties) {
         return '';
     return appends.map(a => `        '${a}',`).join('\n') + '\n';
 }
-function buildCasts(properties, expandedProperties, propertyOrder, reader) {
+function buildCasts(properties, expandedProperties, propertyOrder, reader, config) {
     const casts = [];
+    // Issue #34: cast `EnumRef` properties to their generated PHP enum class.
+    // Use a fully-qualified `\Namespace\FooEnum::class` reference so we don't
+    // need to track imports — Laravel resolves the enum cast by class name.
+    const globalEnumNs = config
+        ? resolveGlobalEnumNamespace(config, config.models.namespace)
+        : '';
     for (const propName of propertyOrder) {
         const prop = properties[propName];
         if (!prop)
             continue;
         const type = prop['type'] ?? 'String';
+        // EnumRef → cast to generated enum class (only when the referenced enum
+        // schema actually exists; otherwise fall through to a plain string).
+        if (type === 'EnumRef') {
+            const enumName = prop['enum'];
+            if (typeof enumName === 'string' && reader.getSchema(enumName)?.kind === 'enum' && globalEnumNs) {
+                const snakeName = toSnakeCase(propName);
+                casts.push(`'${snakeName}' => \\${globalEnumNs}\\${enumClassName(enumName)}::class,`);
+                continue;
+            }
+        }
         if (type === 'Association') {
             const relation = prop['relation'] ?? '';
             if (relation === 'ManyToOne') {

package/ts-dist/php/openapi-generator.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Generates OpenAPI / Swagger annotation files from schemas (issue #35).
+ *
+ * Off by default. Opt in via `codegen.laravel.openapi.enable: true`. Requires
+ * `darkaonline/l5-swagger` (or any zircote/swagger-php consumer) installed in
+ * the host Laravel project.
+ *
+ * Output (under `app/Omnify/OpenApi/` by default):
+ *   - `Common.php`           — `OmnifyFile`, `PaginationMeta`, `ValidationError`
+ *   - `OmnifyApiInfo.php`    — `#[OA\Info]`, security scheme, one `#[OA\Tag]` per schema
+ *   - `Schemas/{Name}Schema.php` — one component per schema with `options.api`
+ *
+ * Controller method attributes are emitted by `controller-generator.ts` —
+ * not here. We only own the standalone OpenAPI scaffold files.
+ */
+import { SchemaReader } from './schema-reader.js';
+import type { GeneratedFile, PhpConfig } from './types.js';
+import type { SchemaDefinition } from '../types.js';
+/** Public entry. Generates the OpenAPI scaffold files. No-op when disabled. */
+export declare function generateOpenApi(reader: SchemaReader, config: PhpConfig): GeneratedFile[];
+/**
+ * Build the `#[OA\Get(...)]` / `#[OA\Post(...)]` attributes for one CRUD
+ * method on a generated controller. Returned as an array of indented attribute
+ * lines ready to splice into the controller template.
+ *
+ * Returns an empty array when openapi codegen is disabled, so callers can
+ * unconditionally interpolate `${attrs.join('\n')}\n` without branching.
+ */
+export declare function buildControllerMethodAttributes(config: PhpConfig, schema: SchemaDefinition, modelName: string, schemaName: string, method: 'index' | 'store' | 'show' | 'update' | 'destroy' | 'lookup' | 'bulkDelete' | 'restore'): string[];
+/** Returns the imports needed by controller files when openapi is enabled. */
+export declare function openApiControllerImports(config: PhpConfig): string[];

package/ts-dist/php/openapi-generator.js

@@ -0,0 +1,566 @@
+/**
+ * Generates OpenAPI / Swagger annotation files from schemas (issue #35).
+ *
+ * Off by default. Opt in via `codegen.laravel.openapi.enable: true`. Requires
+ * `darkaonline/l5-swagger` (or any zircote/swagger-php consumer) installed in
+ * the host Laravel project.
+ *
+ * Output (under `app/Omnify/OpenApi/` by default):
+ *   - `Common.php`           — `OmnifyFile`, `PaginationMeta`, `ValidationError`
+ *   - `OmnifyApiInfo.php`    — `#[OA\Info]`, security scheme, one `#[OA\Tag]` per schema
+ *   - `Schemas/{Name}Schema.php` — one component per schema with `options.api`
+ *
+ * Controller method attributes are emitted by `controller-generator.ts` —
+ * not here. We only own the standalone OpenAPI scaffold files.
+ */
+import { toPascalCase, toSnakeCase, pluralize } from './naming-helper.js';
+import { baseFile } from './types.js';
+/** Public entry. Generates the OpenAPI scaffold files. No-op when disabled. */
+export function generateOpenApi(reader, config) {
+    if (!config.openapi.enable)
+        return [];
+    if (!reader.hasApiSchemas())
+        return [];
+    const files = [];
+    files.push(generateCommonFile(config));
+    files.push(generateInfoFile(reader, config));
+    for (const [name, schema] of Object.entries(reader.getSchemasWithApi())) {
+        files.push(generateSchemaComponent(name, schema, reader, config));
+    }
+    return files;
+}
+// ---------------------------------------------------------------------------
+// Common.php — reusable component schemas referenced from everywhere else
+// ---------------------------------------------------------------------------
+function generateCommonFile(config) {
+    const ns = config.openapi.namespace;
+    const content = `<?php
+
+namespace ${ns};
+
+/**
+ * Reusable OpenAPI component schemas.
+ *
+ * DO NOT EDIT - This file is auto-generated by Omnify.
+ * Any changes will be overwritten on next generation.
+ *
+ * @generated by omnify
+ */
+
+use OpenApi\\Attributes as OA;
+
+#[OA\\Schema(
+    schema: 'OmnifyFile',
+    type: 'object',
+    description: 'A file attached via Omnify\\'s polymorphic file system.',
+    properties: [
+        new OA\\Property(property: 'id', type: 'string'),
+        new OA\\Property(property: 'collection', type: 'string', nullable: true),
+        new OA\\Property(property: 'disk', type: 'string'),
+        new OA\\Property(property: 'path', type: 'string'),
+        new OA\\Property(property: 'original_name', type: 'string'),
+        new OA\\Property(property: 'mime_type', type: 'string'),
+        new OA\\Property(property: 'size', type: 'integer', format: 'int64'),
+        new OA\\Property(property: 'status', type: 'string', enum: ['temporary', 'permanent']),
+        new OA\\Property(property: 'url', type: 'string', nullable: true),
+        new OA\\Property(property: 'expires_at', type: 'string', format: 'date-time', nullable: true),
+        new OA\\Property(property: 'sort_order', type: 'integer'),
+        new OA\\Property(property: 'created_at', type: 'string', format: 'date-time'),
+        new OA\\Property(property: 'updated_at', type: 'string', format: 'date-time'),
+    ],
+)]
+#[OA\\Schema(
+    schema: 'PaginationMeta',
+    type: 'object',
+    description: 'Standard Laravel paginator meta block.',
+    properties: [
+        new OA\\Property(property: 'current_page', type: 'integer'),
+        new OA\\Property(property: 'from', type: 'integer', nullable: true),
+        new OA\\Property(property: 'last_page', type: 'integer'),
+        new OA\\Property(property: 'per_page', type: 'integer'),
+        new OA\\Property(property: 'to', type: 'integer', nullable: true),
+        new OA\\Property(property: 'total', type: 'integer'),
+        new OA\\Property(property: 'path', type: 'string'),
+    ],
+)]
+#[OA\\Schema(
+    schema: 'PaginationLinks',
+    type: 'object',
+    properties: [
+        new OA\\Property(property: 'first', type: 'string', nullable: true),
+        new OA\\Property(property: 'last', type: 'string', nullable: true),
+        new OA\\Property(property: 'prev', type: 'string', nullable: true),
+        new OA\\Property(property: 'next', type: 'string', nullable: true),
+    ],
+)]
+#[OA\\Schema(
+    schema: 'ValidationError',
+    type: 'object',
+    description: 'Standard Laravel 422 validation error envelope.',
+    properties: [
+        new OA\\Property(property: 'message', type: 'string'),
+        new OA\\Property(
+            property: 'errors',
+            type: 'object',
+            additionalProperties: new OA\\AdditionalProperties(
+                type: 'array',
+                items: new OA\\Items(type: 'string'),
+            ),
+        ),
+    ],
+)]
+#[OA\\Schema(
+    schema: 'NotFoundError',
+    type: 'object',
+    properties: [
+        new OA\\Property(property: 'message', type: 'string'),
+    ],
+)]
+final class Common
+{
+    // Marker class — all schemas are declared via attributes above.
+}
+`;
+    return baseFile(`${config.openapi.path}/Common.php`, content);
+}
+// ---------------------------------------------------------------------------
+// OmnifyApiInfo.php — #[OA\Info] + #[OA\Tag] for every API schema
+// ---------------------------------------------------------------------------
+function generateInfoFile(reader, config) {
+    const ns = config.openapi.namespace;
+    const tagsPrefix = config.openapi.tagsPrefix;
+    const securityScheme = config.openapi.securityScheme;
+    const tags = Object.entries(reader.getSchemasWithApi())
+        .map(([name, schema]) => {
+        const tag = `${tagsPrefix}${pluralize(toPascalCase(name))}`;
+        const description = pickLabel(schema.displayName) ?? `${toPascalCase(name)} CRUD endpoints`;
+        return `#[OA\\Tag(name: '${escapePhp(tag)}', description: '${escapePhp(description)}')]`;
+    })
+        .join('\n');
+    const content = `<?php
+
+namespace ${ns};
+
+/**
+ * OpenAPI document root: #[OA\\Info], security schemes and one #[OA\\Tag] per
+ * schema with \`options.api\`.
+ *
+ * DO NOT EDIT - This file is auto-generated by Omnify.
+ * Any changes will be overwritten on next generation.
+ *
+ * @generated by omnify
+ */
+
+use OpenApi\\Attributes as OA;
+
+#[OA\\Info(
+    version: '1.0.0',
+    title: 'API',
+    description: 'Auto-generated by Omnify from schemas.',
+)]
+#[OA\\Server(url: '${escapePhp(config.openapi.pathsPrefix.replace(/\/$/, ''))}', description: 'Default API server')]
+#[OA\\SecurityScheme(
+    securityScheme: '${escapePhp(securityScheme)}',
+    type: 'http',
+    scheme: 'bearer',
+    bearerFormat: 'sanctum',
+)]
+${tags}
+final class OmnifyApiInfo
+{
+    // Marker class — all metadata lives in attributes above.
+}
+`;
+    return baseFile(`${config.openapi.path}/OmnifyApiInfo.php`, content);
+}
+// ---------------------------------------------------------------------------
+// Schemas/{Name}Schema.php — one component per API schema
+// ---------------------------------------------------------------------------
+function generateSchemaComponent(name, schema, reader, config) {
+    const className = `${toPascalCase(name)}Schema`;
+    const ns = `${config.openapi.namespace}\\Schemas`;
+    const componentName = toPascalCase(name);
+    const description = pickLabel(schema.displayName) ?? componentName;
+    const propertyLines = buildSchemaProperties(schema, reader);
+    const content = `<?php
+
+namespace ${ns};
+
+/**
+ * OpenAPI component schema for ${componentName}.
+ *
+ * DO NOT EDIT - This file is auto-generated by Omnify.
+ * Any changes will be overwritten on next generation.
+ *
+ * @generated by omnify
+ */
+
+use OpenApi\\Attributes as OA;
+
+#[OA\\Schema(
+    schema: '${escapePhp(componentName)}',
+    type: 'object',
+    description: '${escapePhp(description)}',
+    properties: [
+${propertyLines.map(l => `        ${l},`).join('\n')}
+    ],
+)]
+final class ${className}
+{
+    // Marker class — schema declared via attributes above.
+}
+`;
+    return baseFile(`${config.openapi.path}/Schemas/${className}.php`, content);
+}
+function buildSchemaProperties(schema, reader) {
+    const lines = [];
+    // ID column (only when auto-ID is on)
+    const idType = schema.options?.id;
+    if (idType !== false) {
+        if (idType === 'Uuid' || idType === 'Ulid' || idType === 'String') {
+            lines.push("new OA\\Property(property: 'id', type: 'string')");
+        }
+        else {
+            lines.push("new OA\\Property(property: 'id', type: 'integer', format: 'int64')");
+        }
+    }
+    const propertyOrder = schema.propertyOrder ?? Object.keys(schema.properties ?? {});
+    const properties = schema.properties ?? {};
+    for (const propName of propertyOrder) {
+        const prop = properties[propName];
+        if (!prop)
+            continue;
+        // Skip explicitly hidden properties (`hidden: true` in YAML — field is
+        // not declared on `PropertyDefinition`, so do an unknown-cast lookup).
+        if (prop.hidden === true)
+            continue;
+        const lineSet = propertyToOpenApi(propName, prop, reader);
+        lines.push(...lineSet);
+    }
+    // Audit columns
+    const audit = schema.options?.audit;
+    if (audit?.createdBy)
+        lines.push("new OA\\Property(property: 'created_by_id', type: 'integer', format: 'int64', nullable: true)");
+    if (audit?.updatedBy)
+        lines.push("new OA\\Property(property: 'updated_by_id', type: 'integer', format: 'int64', nullable: true)");
+    if (audit?.deletedBy)
+        lines.push("new OA\\Property(property: 'deleted_by_id', type: 'integer', format: 'int64', nullable: true)");
+    // Timestamps
+    if (schema.options?.timestamps !== false) {
+        lines.push("new OA\\Property(property: 'created_at', type: 'string', format: 'date-time')");
+        lines.push("new OA\\Property(property: 'updated_at', type: 'string', format: 'date-time')");
+    }
+    if (schema.options?.softDelete) {
+        lines.push("new OA\\Property(property: 'deleted_at', type: 'string', format: 'date-time', nullable: true)");
+    }
+    return lines;
+}
+/**
+ * Convert one schema property into one or more `new OA\Property(...)` lines.
+ * Returns multiple lines for relations (FK column + relation), zero for
+ * unsupported types.
+ */
+function propertyToOpenApi(propName, prop, reader) {
+    const colName = toSnakeCase(propName);
+    const nullable = prop.nullable === true;
+    const type = prop.type;
+    // File: array of OmnifyFile or single OmnifyFile ref.
+    if (type === 'File') {
+        if (prop.multiple) {
+            return [
+                `new OA\\Property(property: '${escapePhp(colName)}', type: 'array', items: new OA\\Items(ref: '#/components/schemas/OmnifyFile'))`,
+            ];
+        }
+        return [
+            `new OA\\Property(property: '${escapePhp(colName)}', ref: '#/components/schemas/OmnifyFile', nullable: ${nullable ? 'true' : 'false'})`,
+        ];
+    }
+    // Association: emit only the FK side here. Eager-loaded relations are out
+    // of scope for the auto-generated component (resource generator decides
+    // whether to expand them).
+    if (type === 'Association') {
+        const relation = prop.relation ?? '';
+        if (relation === 'ManyToOne' || relation === 'OneToOne') {
+            const target = prop.target ?? '';
+            const targetSchema = target ? reader.getSchema(target) : undefined;
+            const targetIdType = targetSchema?.options?.id;
+            const isStringId = targetIdType === 'Uuid' || targetIdType === 'Ulid' || targetIdType === 'String';
+            const fkType = isStringId ? "type: 'string'" : "type: 'integer', format: 'int64'";
+            return [
+                `new OA\\Property(property: '${escapePhp(colName)}_id', ${fkType}, nullable: ${nullable ? 'true' : 'false'})`,
+            ];
+        }
+        // Many-to-many / one-to-many: no scalar FK column on this side.
+        return [];
+    }
+    // EnumRef: resolve the referenced enum schema and embed the values.
+    if (type === 'EnumRef' && typeof prop.enum === 'string') {
+        const enumSchema = reader.getSchema(prop.enum);
+        if (enumSchema?.kind === 'enum') {
+            const values = (enumSchema.values ?? [])
+                .map(v => `'${escapePhp(v.value)}'`)
+                .join(', ');
+            return [
+                `new OA\\Property(property: '${escapePhp(colName)}', type: 'string', enum: [${values}], nullable: ${nullable ? 'true' : 'false'})`,
+            ];
+        }
+    }
+    // Inline Enum: literal values list.
+    if (type === 'Enum' && Array.isArray(prop.enum)) {
+        const values = prop.enum.map(v => `'${escapePhp(String(v))}'`).join(', ');
+        return [
+            `new OA\\Property(property: '${escapePhp(colName)}', type: 'string', enum: [${values}], nullable: ${nullable ? 'true' : 'false'})`,
+        ];
+    }
+    const mapping = toOpenApiType(type);
+    if (!mapping)
+        return [];
+    const parts = [`property: '${escapePhp(colName)}'`, `type: '${mapping.type}'`];
+    if (mapping.format)
+        parts.push(`format: '${mapping.format}'`);
+    // String length: prefer explicit max/maxLength, fall back to `length`.
+    const maxLength = prop.maxLength ?? prop.length;
+    if (mapping.type === 'string' && typeof maxLength === 'number') {
+        parts.push(`maxLength: ${maxLength}`);
+    }
+    if (mapping.type === 'string' && typeof prop.minLength === 'number') {
+        parts.push(`minLength: ${prop.minLength}`);
+    }
+    if ((mapping.type === 'integer' || mapping.type === 'number') && typeof prop.min === 'number') {
+        parts.push(`minimum: ${prop.min}`);
+    }
+    if ((mapping.type === 'integer' || mapping.type === 'number') && typeof prop.max === 'number') {
+        parts.push(`maximum: ${prop.max}`);
+    }
+    parts.push(`nullable: ${nullable ? 'true' : 'false'}`);
+    return [`new OA\\Property(${parts.join(', ')})`];
+}
+/** Map an Omnify property type to its OpenAPI counterpart. */
+function toOpenApiType(type) {
+    switch (type) {
+        case 'String':
+        case 'Slug':
+        case 'Phone':
+        case 'Text':
+        case 'MediumText':
+        case 'LongText':
+            return { type: 'string' };
+        case 'Email':
+            return { type: 'string', format: 'email' };
+        case 'Url':
+            return { type: 'string', format: 'uri' };
+        case 'Password':
+            return { type: 'string', format: 'password' };
+        case 'Uuid':
+            return { type: 'string', format: 'uuid' };
+        case 'Int':
+        case 'BigInt':
+        case 'TinyInt':
+            return { type: 'integer', format: 'int64' };
+        case 'Float':
+        case 'Decimal':
+            return { type: 'number' };
+        case 'Boolean':
+            return { type: 'boolean' };
+        case 'Date':
+            return { type: 'string', format: 'date' };
+        case 'DateTime':
+        case 'Timestamp':
+            return { type: 'string', format: 'date-time' };
+        case 'Time':
+            return { type: 'string' };
+        case 'Json':
+        case 'Point':
+        case 'Coordinates':
+            return { type: 'object' };
+        default:
+            return null;
+    }
+}
+/**
+ * Build the `#[OA\Get(...)]` / `#[OA\Post(...)]` attributes for one CRUD
+ * method on a generated controller. Returned as an array of indented attribute
+ * lines ready to splice into the controller template.
+ *
+ * Returns an empty array when openapi codegen is disabled, so callers can
+ * unconditionally interpolate `${attrs.join('\n')}\n` without branching.
+ */
+export function buildControllerMethodAttributes(config, schema, modelName, schemaName, method) {
+    if (!config.openapi.enable)
+        return [];
+    const tag = `${config.openapi.tagsPrefix}${pluralize(toPascalCase(schemaName))}`;
+    const prefix = (schema.options?.api?.prefix ?? pluralize(toSnakeCase(schemaName))).replace(/^\/+|\/+$/g, '');
+    const basePath = `${config.openapi.pathsPrefix.replace(/\/$/, '')}/${prefix}`;
+    const security = `[['${escapePhp(config.openapi.securityScheme)}' => []]]`;
+    const componentRef = `'#/components/schemas/${escapePhp(toPascalCase(schemaName))}'`;
+    const collectionResponse = (status) => `        new OA\\Response(
+            response: ${status},
+            description: 'OK',
+            content: new OA\\JsonContent(
+                properties: [
+                    new OA\\Property(property: 'data', type: 'array', items: new OA\\Items(ref: ${componentRef})),
+                    new OA\\Property(property: 'meta', ref: '#/components/schemas/PaginationMeta'),
+                    new OA\\Property(property: 'links', ref: '#/components/schemas/PaginationLinks'),
+                ],
+            ),
+        ),`;
+    const singleResponse = (status, description = 'OK') => `        new OA\\Response(
+            response: ${status},
+            description: '${escapePhp(description)}',
+            content: new OA\\JsonContent(
+                properties: [
+                    new OA\\Property(property: 'data', ref: ${componentRef}),
+                ],
+            ),
+        ),`;
+    const errorResponses = `        new OA\\Response(response: 401, description: 'Unauthenticated'),
+        new OA\\Response(response: 403, description: 'Forbidden'),
+        new OA\\Response(response: 404, description: 'Not found', content: new OA\\JsonContent(ref: '#/components/schemas/NotFoundError')),`;
+    const validationResponse = `        new OA\\Response(response: 422, description: 'Validation error', content: new OA\\JsonContent(ref: '#/components/schemas/ValidationError')),`;
+    switch (method) {
+        case 'index': {
+            return wrapAttribute(`#[OA\\Get(
+        path: '${escapePhp(basePath)}',
+        summary: 'List ${escapePhp(modelName)}',
+        tags: ['${escapePhp(tag)}'],
+        security: ${security},
+        parameters: [
+            new OA\\Parameter(name: 'search', in: 'query', required: false, schema: new OA\\Schema(type: 'string')),
+            new OA\\Parameter(name: 'sort', in: 'query', required: false, schema: new OA\\Schema(type: 'string')),
+            new OA\\Parameter(name: 'per_page', in: 'query', required: false, schema: new OA\\Schema(type: 'integer', default: ${schema.options?.api?.perPage ?? 15})),
+            new OA\\Parameter(name: 'page', in: 'query', required: false, schema: new OA\\Schema(type: 'integer')),
+        ],
+        responses: [
+${collectionResponse(200)}
+${errorResponses}
+        ],
+    )]`);
+        }
+        case 'store':
+            return wrapAttribute(`#[OA\\Post(
+        path: '${escapePhp(basePath)}',
+        summary: 'Create ${escapePhp(modelName)}',
+        tags: ['${escapePhp(tag)}'],
+        security: ${security},
+        requestBody: new OA\\RequestBody(required: true, content: new OA\\JsonContent(ref: ${componentRef})),
+        responses: [
+${singleResponse(201, 'Created')}
+${errorResponses}
+${validationResponse}
+        ],
+    )]`);
+        case 'show':
+            return wrapAttribute(`#[OA\\Get(
+        path: '${escapePhp(basePath)}/{id}',
+        summary: 'Show ${escapePhp(modelName)}',
+        tags: ['${escapePhp(tag)}'],
+        security: ${security},
+        parameters: [
+            new OA\\Parameter(name: 'id', in: 'path', required: true, schema: new OA\\Schema(type: 'string')),
+        ],
+        responses: [
+${singleResponse(200)}
+${errorResponses}
+        ],
+    )]`);
+        case 'update':
+            return wrapAttribute(`#[OA\\Put(
+        path: '${escapePhp(basePath)}/{id}',
+        summary: 'Update ${escapePhp(modelName)}',
+        tags: ['${escapePhp(tag)}'],
+        security: ${security},
+        parameters: [
+            new OA\\Parameter(name: 'id', in: 'path', required: true, schema: new OA\\Schema(type: 'string')),
+        ],
+        requestBody: new OA\\RequestBody(required: true, content: new OA\\JsonContent(ref: ${componentRef})),
+        responses: [
+${singleResponse(200)}
+${errorResponses}
+${validationResponse}
+        ],
+    )]`);
+        case 'destroy':
+            return wrapAttribute(`#[OA\\Delete(
+        path: '${escapePhp(basePath)}/{id}',
+        summary: 'Delete ${escapePhp(modelName)}',
+        tags: ['${escapePhp(tag)}'],
+        security: ${security},
+        parameters: [
+            new OA\\Parameter(name: 'id', in: 'path', required: true, schema: new OA\\Schema(type: 'string')),
+        ],
+        responses: [
+            new OA\\Response(response: 204, description: 'No content'),
+${errorResponses}
+        ],
+    )]`);
+        case 'lookup':
+            return wrapAttribute(`#[OA\\Get(
+        path: '${escapePhp(basePath)}/lookup',
+        summary: 'Lookup ${escapePhp(modelName)} (lightweight collection for selects)',
+        tags: ['${escapePhp(tag)}'],
+        security: ${security},
+        parameters: [
+            new OA\\Parameter(name: 'search', in: 'query', required: false, schema: new OA\\Schema(type: 'string')),
+        ],
+        responses: [
+${collectionResponse(200)}
+${errorResponses}
+        ],
+    )]`);
+        case 'bulkDelete':
+            return wrapAttribute(`#[OA\\Post(
+        path: '${escapePhp(basePath)}/bulk-delete',
+        summary: 'Bulk delete ${escapePhp(modelName)}',
+        tags: ['${escapePhp(tag)}'],
+        security: ${security},
+        requestBody: new OA\\RequestBody(required: true, content: new OA\\JsonContent(
+            properties: [
+                new OA\\Property(property: 'ids', type: 'array', items: new OA\\Items(type: 'string')),
+            ],
+        )),
+        responses: [
+            new OA\\Response(response: 204, description: 'No content'),
+${errorResponses}
+${validationResponse}
+        ],
+    )]`);
+        case 'restore':
+            return wrapAttribute(`#[OA\\Post(
+        path: '${escapePhp(basePath)}/{id}/restore',
+        summary: 'Restore ${escapePhp(modelName)}',
+        tags: ['${escapePhp(tag)}'],
+        security: ${security},
+        parameters: [
+            new OA\\Parameter(name: 'id', in: 'path', required: true, schema: new OA\\Schema(type: 'string')),
+        ],
+        responses: [
+${singleResponse(200, 'Restored')}
+${errorResponses}
+        ],
+    )]`);
+    }
+}
+/** Returns the imports needed by controller files when openapi is enabled. */
+export function openApiControllerImports(config) {
+    if (!config.openapi.enable)
+        return [];
+    return ['use OpenApi\\Attributes as OA;'];
+}
+// ---------------------------------------------------------------------------
+// helpers
+// ---------------------------------------------------------------------------
+/** Wrap a multi-line attribute string into the array format the caller expects. */
+function wrapAttribute(attr) {
+    return attr.split('\n');
+}
+function escapePhp(value) {
+    return value.replace(/\\/g, '\\\\').replace(/'/g, "\\'");
+}
+/** Pick a sensible default label from a localized string for descriptions. */
+function pickLabel(displayName) {
+    if (!displayName)
+        return null;
+    if (typeof displayName === 'string')
+        return displayName;
+    return displayName.en ?? displayName.ja ?? Object.values(displayName)[0] ?? null;
+}

package/ts-dist/php/types.d.ts

@@ -61,6 +61,32 @@ export interface LaravelPathOverride {
 export interface NestedSetOverride {
     namespace?: string;
 }
+/**
+ * OpenAPI / Swagger annotation generation override (issue #35).
+ * Opt-in: only emits files / attributes when `enable: true`.
+ *
+ * Generates `OpenApi/Common.php`, `OpenApi/OmnifyApiInfo.php`, and one
+ * `OpenApi/Schemas/{Name}Schema.php` per schema with `options.api`. When
+ * enabled, also injects `#[OA\Get/Post/...]` attributes onto the auto-generated
+ * controller CRUD methods so docs stay in sync with the actual handlers.
+ *
+ * Requires `darkaonline/l5-swagger` (or any zircote/swagger-php consumer)
+ * installed in the target Laravel project.
+ */
+export interface OpenApiOverride {
+    /** Toggle OpenAPI codegen on/off. Off by default — opt-in feature. */
+    enable?: boolean;
+    /** PHP namespace for the generated `OpenApi/...` classes. Default `App\Omnify\OpenApi`. */
+    namespace?: string;
+    /** Filesystem path for the generated `OpenApi/...` files. Default `app/Omnify/OpenApi`. */
+    path?: string;
+    /** URL prefix prepended to every generated path attribute. Default `/api/v1`. */
+    pathsPrefix?: string;
+    /** Optional prefix for tag names (e.g. `Brand` → `BrandProducts`). */
+    tagsPrefix?: string;
+    /** Name of the OpenAPI security scheme to attach to every endpoint. Default `sanctum`. */
+    securityScheme?: string;
+}
 /** Overrides from codegen.laravel YAML config (all optional). */
 export interface LaravelCodegenOverrides {
     /**
@@ -102,6 +128,8 @@ export interface LaravelCodegenOverrides {
     route?: LaravelPathOverride;
     config?: LaravelPathOverride;
     nestedset?: NestedSetOverride;
+    /** OpenAPI / Swagger codegen — opt-in. See `OpenApiOverride`. */
+    openapi?: OpenApiOverride;
 }
 /** PHP codegen configuration (resolved with defaults). */
 export interface PhpConfig {
@@ -192,6 +220,15 @@ export interface PhpConfig {
     nestedset: {
         namespace: string;
     };
+    /** OpenAPI / Swagger codegen config (issue #35). */
+    openapi: {
+        enable: boolean;
+        namespace: string;
+        path: string;
+        pathsPrefix: string;
+        tagsPrefix: string;
+        securityScheme: string;
+    };
 }
 /**
  * Derive full PHP config from optional overrides.

package/ts-dist/php/types.js

@@ -155,6 +155,7 @@ const DEFAULT_MODULES_PATH = 'app/Omnify/Modules';
 const DEFAULT_SHARED_PATH = 'app/Omnify/Shared';
 const DEFAULT_GLOBAL_ENUMS_PATH = 'app/Omnify/Enums';
 const DEFAULT_GLOBAL_TRAITS_PATH = 'app/Omnify/Traits';
+const DEFAULT_OPENAPI_PATH = 'app/Omnify/OpenApi';
 /**
  * Apply a rootPath prefix to a path. Absolute paths and paths that already
  * begin with `${rootPath}/` are returned as-is, so users can mix and match
@@ -203,6 +204,13 @@ export function derivePhpConfig(overrides) {
     const routePath = withRoot(rootPath, overrides?.route?.path ?? DEFAULT_ROUTE_PATH);
     const configFilePath = withRoot(rootPath, overrides?.config?.path ?? DEFAULT_CONFIG_FILE_PATH);
     const nestedsetNs = overrides?.nestedset?.namespace ?? 'Aimeos\\Nestedset';
+    // OpenAPI codegen (issue #35) — re-uses the same path/namespace derivation
+    // helper as every other layer so a single `namespace` override stays in sync
+    // with the file path (and vice-versa).
+    const openapiOverride = overrides?.openapi;
+    const { path: openapiPath, namespace: openapiNs } = resolvePathAndNamespace(rootPath, openapiOverride && (openapiOverride.path !== undefined || openapiOverride.namespace !== undefined)
+        ? { path: openapiOverride.path, namespace: openapiOverride.namespace }
+        : undefined, DEFAULT_OPENAPI_PATH, nsFromPath);
     const structure = overrides?.structure ?? 'legacy';
     return {
         rootPath,
@@ -265,5 +273,13 @@ export function derivePhpConfig(overrides) {
         nestedset: {
             namespace: nestedsetNs,
         },
+        openapi: {
+            enable: openapiOverride?.enable ?? false,
+            namespace: openapiNs,
+            path: openapiPath,
+            pathsPrefix: openapiOverride?.pathsPrefix ?? '/api/v1',
+            tagsPrefix: openapiOverride?.tagsPrefix ?? '',
+            securityScheme: openapiOverride?.securityScheme ?? 'sanctum',
+        },
     };
 }