@omnifyjp/omnify 3.6.0 → 3.7.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@omnifyjp/omnify",
-  "version": "3.6.0",
+  "version": "3.7.1",
   "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.6.0",
-    "@omnifyjp/omnify-darwin-x64": "3.6.0",
-    "@omnifyjp/omnify-linux-x64": "3.6.0",
-    "@omnifyjp/omnify-linux-arm64": "3.6.0",
-    "@omnifyjp/omnify-win32-x64": "3.6.0"
+    "@omnifyjp/omnify-darwin-arm64": "3.7.1",
+    "@omnifyjp/omnify-darwin-x64": "3.7.1",
+    "@omnifyjp/omnify-linux-x64": "3.7.1",
+    "@omnifyjp/omnify-linux-arm64": "3.7.1",
+    "@omnifyjp/omnify-win32-x64": "3.7.1"
   }
 }

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/index.js

@@ -31,6 +31,7 @@ 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) {
@@ -61,6 +62,11 @@ 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));

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/request-generator.js

@@ -4,6 +4,24 @@
 import { toPascalCase, toSnakeCase, toCamelCase } from './naming-helper.js';
 import { toStoreRules, toUpdateRules, formatRules, hasRuleObject } from './type-mapper.js';
 import { baseFile, userFile, resolveModularBasePath, resolveModularBaseNamespace } from './types.js';
+/**
+ * Resolve the Laravel validation rule type ('integer', 'uuid', or 'string') for
+ * a foreign key column based on the target schema's primary key type.
+ *
+ * Mirrors the FK cast logic in `model-generator.ts` so validation rules and
+ * Eloquent casts agree about the wire format. Issue #36.
+ */
+function resolveFkRuleType(target, reader) {
+    if (!target)
+        return 'integer';
+    const targetSchema = reader.getSchema(target);
+    const id = targetSchema?.options?.id;
+    if (id === 'Uuid')
+        return 'uuid';
+    if (id === 'Ulid' || id === 'String')
+        return 'string';
+    return 'integer';
+}
 /** Generate Store/Update request classes for all project-owned visible object schemas. */
 export function generateRequests(reader, config) {
     const files = [];
@@ -78,9 +96,11 @@ function generateBaseRequest(name, schema, reader, config, action) {
             const relation = prop['relation'] ?? '';
             if (relation === 'ManyToOne') {
                 const snakeName = toSnakeCase(propName) + '_id';
+                const target = prop['target'] ?? '';
+                const targetIdType = resolveFkRuleType(target, reader);
                 const rules = isUpdate
-                    ? toUpdateRules(prop, tableName, modelRouteParam)
-                    : toStoreRules(prop, tableName);
+                    ? toUpdateRules(prop, tableName, modelRouteParam, targetIdType)
+                    : toStoreRules(prop, tableName, targetIdType);
                 rulesLines.push(`            '${snakeName}' => ${formatRules(rules)},`);
                 attributeKeys.push(snakeName);
             }

package/ts-dist/php/type-mapper.d.ts

@@ -6,10 +6,17 @@ type Rule = string | ['rule_in', string[]] | ['rule_unique_ignore', string, stri
 export declare function toCast(type: string, property?: Record<string, unknown>): string | null;
 /** Map Omnify property type to PHP doc type. */
 export declare function toPhpDocType(type: string, nullable?: boolean): string;
-/** Generate validation rules for a property (Store request). */
-export declare function toStoreRules(property: Record<string, unknown>, tableName: string): Rule[];
+/**
+ * Generate validation rules for a property (Store request).
+ *
+ * @param fkRuleType - For ManyToOne associations, the validation rule type
+ *   matching the target schema's primary key ('integer' for Int/BigInt PKs,
+ *   'uuid' for Uuid PKs, 'string' for Ulid/String PKs). Defaults to 'integer'
+ *   for backwards compatibility. Issue #36.
+ */
+export declare function toStoreRules(property: Record<string, unknown>, tableName: string, fkRuleType?: 'integer' | 'uuid' | 'string'): Rule[];
 /** Generate validation rules for a property (Update request). */
-export declare function toUpdateRules(property: Record<string, unknown>, tableName: string, modelRouteParam: string): Rule[];
+export declare function toUpdateRules(property: Record<string, unknown>, tableName: string, modelRouteParam: string, fkRuleType?: 'integer' | 'uuid' | 'string'): Rule[];
 /** Format validation rules as PHP code string. */
 export declare function formatRules(rules: Rule[]): string;
 /** Resolve enum values from property definition. */

package/ts-dist/php/type-mapper.js

@@ -70,8 +70,15 @@ const STRING_TYPES = new Set([
 ]);
 const NUMERIC_TYPES = new Set(['Int', 'BigInt', 'TinyInt', 'Float', 'Decimal']);
 const ARRAY_TYPES = new Set(['Json']);
-/** Generate validation rules for a property (Store request). */
-export function toStoreRules(property, tableName) {
+/**
+ * Generate validation rules for a property (Store request).
+ *
+ * @param fkRuleType - For ManyToOne associations, the validation rule type
+ *   matching the target schema's primary key ('integer' for Int/BigInt PKs,
+ *   'uuid' for Uuid PKs, 'string' for Ulid/String PKs). Defaults to 'integer'
+ *   for backwards compatibility. Issue #36.
+ */
+export function toStoreRules(property, tableName, fkRuleType = 'integer') {
     const type = property['type'] ?? 'String';
     // File type defaults to nullable (uploads are optional, attached separately)
     const nullable = property['nullable'] ?? (type === 'File' ? true : false);
@@ -143,7 +150,7 @@ export function toStoreRules(property, tableName) {
         case 'Association': {
             const relation = property['relation'] ?? '';
             if (relation === 'ManyToOne') {
-                rules.push('integer');
+                rules.push(fkRuleType);
                 const target = property['target'] ?? '';
                 if (target)
                     rules.push(`exists:${toTableName(target)},id`);
@@ -267,8 +274,8 @@ function mergeValidationRules(rules, vr, type) {
     }
 }
 /** Generate validation rules for a property (Update request). */
-export function toUpdateRules(property, tableName, modelRouteParam) {
-    let rules = toStoreRules(property, tableName);
+export function toUpdateRules(property, tableName, modelRouteParam, fkRuleType = 'integer') {
+    let rules = toStoreRules(property, tableName, fkRuleType);
     const unique = property['unique'] ?? false;
     // Replace 'required' with 'sometimes'
     rules = rules.map(r => r === 'required' ? 'sometimes' : r);

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',
+        },
     };
 }