@enzopita/adonisjs-openapi 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Enzo Pita <enzo@enzopita.com>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,65 @@
-# Temporary Holding Version
+# @enzopita/adonisjs-openapi
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Generate an OpenAPI 3.1 document from an AdonisJS 7 app, with no annotations. The generator reads the same sources as [Tuyau](https://github.com/Julien-R44/tuyau):
+
+| OpenAPI                             | Source                                                                                         |
+| ----------------------------------- | ---------------------------------------------------------------------------------------------- |
+| Paths and operations                | Named routes from the router                                                                   |
+| Request body, query and path params | The VineJS validator passed to `request.validateUsing()` (formats, bounds and enums included)  |
+| Responses                           | The return type of the controller method, such as `serialize(UserTransformer.transform(user))` |
+| `422` response                      | Added to every route that validates its input                                                  |
+| `security`                          | Named middleware on the route, mapped in the config                                            |
+
+## Install
+
+```sh
+node ace add @enzopita/adonisjs-openapi
+```
+
+The command installs the package, registers its ace command in `adonisrc.ts`, and creates `config/openapi.ts`. The package needs `@adonisjs/assembler`, which every AdonisJS app has as a dev dependency.
+
+## Generate the document
+
+```sh
+node ace openapi:generate
+```
+
+The command boots the app the way `node ace codegen` does, so no database connection or queue worker starts. It writes `openapi.json` at the app root. To write it somewhere else, pass `--output=public/openapi.json` or set `output` in the config.
+
+## Configure
+
+```ts
+// config/openapi.ts
+import { defineConfig } from '@enzopita/adonisjs-openapi'
+
+export default defineConfig({
+  output: 'openapi.json',
+  info: { title: 'Acme API', version: '1.0.0' },
+  servers: [{ url: 'https://api.acme.test' }],
+  routes: { except: ['admin.'] },
+  securitySchemes: {
+    accessToken: { type: 'http', scheme: 'bearer' },
+  },
+  middlewareSecurity: {
+    auth: 'accessToken',
+  },
+})
+```
+
+- `routes` takes `only` or `except`, with the same matchers as Tuyau's `generateRegistry()`: a substring, a regular expression, or a function of the route name.
+- `middlewareSecurity` maps a named middleware, such as `middleware.auth()`, to a key of `securitySchemes`.
+
+## How types become schemas
+
+- A route must have a name and a controller handler. Closure routes are skipped, as they are in Tuyau.
+- On `GET` routes, the validator fields become query parameters. On other methods they become the body, and the validator's `query` and `params` objects become query and path parameters.
+- A body with a `vine.file()` field is sent as `multipart/form-data`.
+- When VineJS cannot describe a field (a file, a custom rule), the generator uses the field's TypeScript type.
+- `Date` and Luxon `DateTime` values become `{ type: 'string', format: 'date-time' }`.
+- A handler that returns a model or an untyped object produces a `200` response with no schema and a warning. Return `serialize(...)` to type it.
+
+## Limitations
+
+- Schemas are inlined. Transformers do not become named components yet.
+- Operations have no `summary` or `description` yet.
+- Status codes other than `200` and `422` come only from return types that carry a `__status`, which no AdonisJS 7.6 API produces yet.

package/build/commands/generate_openapi.d.ts

@@ -0,0 +1,8 @@
+import { BaseCommand } from '@adonisjs/core/ace';
+export default class GenerateOpenApi extends BaseCommand {
+    #private;
+    static commandName: string;
+    static description: string;
+    output?: string;
+    run(): Promise<void>;
+}

package/build/commands/generate_openapi.js

@@ -0,0 +1,49 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+import { dirname, join } from 'node:path';
+import { mkdir, writeFile } from 'node:fs/promises';
+import { fileURLToPath } from 'node:url';
+import { BaseCommand, flags } from '@adonisjs/core/ace';
+import { defineConfig } from "../src/define_config.js";
+export default class GenerateOpenApi extends BaseCommand {
+    static commandName = 'openapi:generate';
+    static description = 'Generate an OpenAPI document from the routes, validators and transformers';
+    /**
+     * Same warm-up as `node ace codegen`: the app is assembled like the web
+     * environment, but never becomes ready, so no long-running side effect starts.
+     */
+    async #warmUpApp() {
+        this.app.setEnvironment('web');
+        this.app.setMode('warmup');
+        await this.app.boot();
+        await this.app.warmUp();
+        const router = await this.app.container.make('router');
+        router.commit();
+        return router;
+    }
+    async run() {
+        const router = await this.#warmUpApp();
+        const config = this.app.config.get('openapi') ?? defineConfig();
+        const startTime = process.hrtime();
+        // Loaded on run: it pulls in the TypeScript compiler, which every other ace command would pay for.
+        const { generateDocument } = await import("../src/generate.js");
+        const { document, warnings } = await generateDocument(this.app, router, config);
+        for (const warning of warnings)
+            this.logger.warning(warning);
+        const output = join(fileURLToPath(this.app.appRoot), this.output ?? config.output);
+        await mkdir(dirname(output), { recursive: true });
+        await writeFile(output, `${JSON.stringify(document, null, 2)}\n`);
+        this.logger.success(`OpenAPI document written to ${this.app.relativePath(output)}`, {
+            startTime,
+        });
+    }
+}
+__decorate([
+    flags.string({
+        description: 'Output file, relative to the app root. Defaults to config/openapi.ts "output"',
+    })
+], GenerateOpenApi.prototype, "output", void 0);

package/build/commands/main.d.ts

@@ -0,0 +1,4 @@
+import type { CommandMetaData } from '@adonisjs/core/types/ace';
+import GenerateOpenApi from './generate_openapi.ts';
+export declare function getMetaData(): Promise<CommandMetaData[]>;
+export declare function getCommand(metaData: CommandMetaData): Promise<typeof GenerateOpenApi | null>;

package/build/commands/main.js

@@ -0,0 +1,7 @@
+import GenerateOpenApi from "./generate_openapi.js";
+export async function getMetaData() {
+    return [{ ...GenerateOpenApi.serialize(), filePath: 'generate_openapi.js' }];
+}
+export async function getCommand(metaData) {
+    return metaData.commandName === GenerateOpenApi.commandName ? GenerateOpenApi : null;
+}

package/build/configure.d.ts

@@ -0,0 +1,2 @@
+import type Configure from '@adonisjs/core/commands/configure';
+export declare function configure(command: Configure): Promise<void>;

package/build/configure.js

@@ -0,0 +1,8 @@
+import { stubsRoot } from "./stubs/main.js";
+export async function configure(command) {
+    const codemods = await command.createCodemods();
+    await codemods.makeUsingStub(stubsRoot, 'config/openapi.stub', {});
+    await codemods.updateRcFile(rcFile => {
+        rcFile.addCommand('@enzopita/adonisjs-openapi/commands');
+    });
+}

package/build/index.d.ts

@@ -0,0 +1,4 @@
+export { configure } from './configure.ts';
+export { defineConfig } from './src/define_config.ts';
+export { generateDocument } from './src/generate.ts';
+export { stubsRoot } from './stubs/main.ts';

package/build/index.js

@@ -0,0 +1,4 @@
+export { configure } from "./configure.js";
+export { defineConfig } from "./src/define_config.js";
+export { generateDocument } from "./src/generate.js";
+export { stubsRoot } from "./stubs/main.js";

package/build/src/collect_routes.d.ts

@@ -0,0 +1,7 @@
+import type { Router } from '@adonisjs/core/http';
+import type { OpenApiConfig, RouteOperation } from './types.ts';
+/**
+ * Scans the committed router with the same routes scanner the dev server feeds
+ * Tuyau, so both see the same request and response types.
+ */
+export declare function collectRoutes(appRoot: string, router: Router, config: OpenApiConfig): Promise<RouteOperation[]>;

package/build/src/collect_routes.js

@@ -0,0 +1,60 @@
+import { RoutesScanner } from '@adonisjs/assembler/routes_scanner';
+const METHODS = new Set(['get', 'post', 'put', 'patch', 'delete', 'options']);
+function matches(routeName, matcher) {
+    if (matcher instanceof RegExp)
+        return matcher.test(routeName);
+    if (matcher instanceof Function)
+        return matcher(routeName);
+    return routeName.includes(matcher);
+}
+function isIncluded(routeName, filters) {
+    if (filters.only)
+        return filters.only.some(matcher => matches(routeName, matcher));
+    if (filters.except)
+        return !filters.except.some(matcher => matches(routeName, matcher));
+    return true;
+}
+/**
+ * `/users/:id/:slug?` becomes `/users/{id}/{slug}`, the only form OpenAPI paths accept.
+ */
+function toOpenApiPath(pattern) {
+    return pattern.replace(/:([^/?]+)\??/g, '{$1}').replace(/\*/g, '{wildcard}');
+}
+/**
+ * Scans the committed router with the same routes scanner the dev server feeds
+ * Tuyau, so both see the same request and response types.
+ */
+export async function collectRoutes(appRoot, router, config) {
+    const live = router.toJSON();
+    const middlewareByRoute = new Map();
+    for (const route of Object.values(live).flat()) {
+        const names = [...route.middleware.all()].flatMap(entry => 'name' in entry && entry.name ? [entry.name] : []);
+        middlewareByRoute.set(`${route.domain}:${route.pattern}:${route.methods.join(',')}`, names);
+    }
+    // Round-tripped through JSON like the dev server and `node ace codegen` do, which drops closure handlers.
+    const serialized = JSON.parse(JSON.stringify(live));
+    const scanner = new RoutesScanner(appRoot, []);
+    scanner.filter(route => isIncluded(route.name ?? '', config.routes));
+    for (const routes of Object.values(serialized))
+        await scanner.scan(routes);
+    return scanner.getScannedRoutes().map(route => {
+        const pattern = toOpenApiPath(route.pattern);
+        const [validator] = route.validators ?? [];
+        return {
+            name: route.name,
+            methods: route.methods
+                .map(method => method.toLowerCase())
+                .filter((method) => METHODS.has(method)),
+            path: pattern,
+            pathParams: [...pattern.matchAll(/\{([^}]+)\}/g)].map(match => match[1]),
+            middleware: middlewareByRoute.get(`${route.domain}:${route.pattern}:${route.methods.join(',')}`) ?? [],
+            requestType: route.request?.type,
+            responseType: route.response?.type,
+            imports: [...(route.request?.imports ?? []), ...(route.response?.imports ?? [])],
+            validator: validator && {
+                specifier: validator.import.specifier,
+                exportName: validator.import.value,
+            },
+        };
+    });
+}

package/build/src/define_config.d.ts

@@ -0,0 +1,2 @@
+import type { OpenApiConfig } from './types.ts';
+export declare function defineConfig(config?: Partial<OpenApiConfig>): OpenApiConfig;

package/build/src/define_config.js

@@ -0,0 +1,14 @@
+export function defineConfig(config = {}) {
+    if (config.routes?.only && config.routes.except) {
+        throw new Error('openapi: use either "routes.only" or "routes.except", not both');
+    }
+    return {
+        output: 'openapi.json',
+        info: { title: 'API', version: '1.0.0' },
+        servers: [],
+        routes: {},
+        securitySchemes: {},
+        middlewareSecurity: {},
+        ...config,
+    };
+}

package/build/src/generate.d.ts

@@ -0,0 +1,8 @@
+import type { ApplicationService } from '@adonisjs/core/types';
+import type { Router } from '@adonisjs/core/http';
+import type { OpenApiConfig, OpenApiDocument } from './types.ts';
+export interface GeneratedDocument {
+    document: OpenApiDocument;
+    warnings: string[];
+}
+export declare function generateDocument(app: ApplicationService, router: Router, config: OpenApiConfig): Promise<GeneratedDocument>;

package/build/src/generate.js

@@ -0,0 +1,148 @@
+import { STATUS_CODES } from 'node:http';
+import { fileURLToPath } from 'node:url';
+import ts from 'typescript';
+import { collectRoutes } from "./collect_routes.js";
+import { RouteTypes } from "./route_types.js";
+const NOT_IN_BODY = new Set(['query', 'params', 'headers', 'cookies']);
+/**
+ * Vine knows the constraints (formats, bounds, enums) but has no JSON Schema for
+ * files or custom rules and emits `{}` there: the TypeScript shape fills those gaps.
+ */
+function mergeSchemas(vine, typed) {
+    if (!vine || !Object.keys(vine).length)
+        return typed;
+    if (!vine.properties || !typed.properties)
+        return vine;
+    const typedProperties = typed.properties;
+    const properties = Object.fromEntries(Object.entries(vine.properties).map(([key, schema]) => [
+        key,
+        mergeSchemas(schema, typedProperties[key] ?? {}),
+    ]));
+    return { ...vine, properties };
+}
+function pick(schema, keep) {
+    const properties = Object.entries(schema.properties ?? {}).filter(([key]) => keep(key));
+    if (!properties.length)
+        return undefined;
+    const { required = [], ...rest } = schema;
+    const kept = required.filter(keep);
+    return kept.length
+        ? { ...rest, properties: Object.fromEntries(properties), required: kept }
+        : { ...rest, properties: Object.fromEntries(properties) };
+}
+async function validatorSchemas(app, routes, warnings) {
+    const schemas = new Map();
+    for (const route of routes) {
+        if (!route.validator)
+            continue;
+        const { specifier, exportName } = route.validator;
+        try {
+            // SAFETY: the routes scanner only reports values passed to `request.validateUsing()`, which are Vine validators.
+            const module = (await app.import(specifier));
+            const validator = module[exportName];
+            if (validator)
+                schemas.set(route.name, validator.toJSONSchema());
+        }
+        catch (error) {
+            const reason = error instanceof Error ? error.message : String(error);
+            warnings.push(`${route.name}: cannot read the JSON Schema of ${specifier}#${exportName} (${reason})`);
+        }
+    }
+    return schemas;
+}
+function responsesFor(route, types, response, warnings) {
+    const responses = {};
+    const describe = (code, schema) => {
+        responses[code] = {
+            description: STATUS_CODES[Number(code)] ?? 'Response',
+            content: { 'application/json': { schema } },
+        };
+    };
+    const members = response?.isUnion() ? response.types : response ? [response] : [];
+    for (const member of members) {
+        const status = types.property(member, '__status');
+        const payload = types.property(member, '__response');
+        if (status && payload) {
+            describe(status.isNumberLiteral() ? String(status.value) : 'default', types.schemas.convert(payload));
+        }
+        else if (!(member.flags & (ts.TypeFlags.Any | ts.TypeFlags.Unknown))) {
+            describe('200', types.schemas.convert(member));
+        }
+    }
+    const validationError = route.validator && types.validationError();
+    if (validationError)
+        describe('422', types.schemas.convert(validationError));
+    if (!Object.keys(responses).some(code => code.startsWith('2') || code === 'default')) {
+        warnings.push(`${route.name}: the handler's return type is unknown, returning serialize(...) makes it typed`);
+        responses['200'] = { description: 'OK' };
+    }
+    return responses;
+}
+function parametersFor(route, query, params) {
+    const path = route.pathParams.map((name) => ({
+        name,
+        in: 'path',
+        required: true,
+        schema: params?.properties?.[name] ?? { type: 'string' },
+    }));
+    const search = Object.entries(query?.properties ?? {}).map(([name, schema]) => ({
+        name,
+        in: 'query',
+        required: query?.required?.includes(name) ?? false,
+        schema,
+    }));
+    return [...path, ...search];
+}
+export async function generateDocument(app, router, config) {
+    const warnings = [];
+    const appRoot = fileURLToPath(app.appRoot);
+    const routes = await collectRoutes(appRoot, router, config);
+    const types = new RouteTypes(appRoot, routes);
+    const vine = await validatorSchemas(app, routes, warnings);
+    const paths = {};
+    for (const route of routes) {
+        const { request, response } = types.get(route.name);
+        const input = request && mergeSchemas(vine.get(route.name), types.schemas.convert(request));
+        const readsQueryOnly = route.methods.every(method => method === 'get' || method === 'options');
+        const fields = input && pick(input, key => !NOT_IN_BODY.has(key));
+        const body = readsQueryOnly ? undefined : fields;
+        const query = readsQueryOnly ? fields : input?.properties?.query;
+        const parameters = parametersFor(route, query, input?.properties?.params);
+        const security = route.middleware.flatMap(name => {
+            const scheme = config.middlewareSecurity[name];
+            return scheme ? [{ [scheme]: [] }] : [];
+        });
+        const operation = {
+            tags: [route.name.split('.')[0] ?? route.name],
+            responses: responsesFor(route, types, response, warnings),
+        };
+        if (parameters.length)
+            operation.parameters = parameters;
+        if (security.length)
+            operation.security = security;
+        if (body) {
+            const mediaType = JSON.stringify(body).includes('"format":"binary"')
+                ? 'multipart/form-data'
+                : 'application/json';
+            operation.requestBody = { required: true, content: { [mediaType]: { schema: body } } };
+        }
+        const methods = paths[route.path] ?? {};
+        paths[route.path] = methods;
+        for (const method of route.methods) {
+            const operationId = route.methods.length > 1 ? `${route.name}.${method}` : route.name;
+            methods[method] = { operationId, ...operation };
+        }
+    }
+    for (const type of types.schemas.unsupported) {
+        warnings.push(`no JSON Schema for the type ${type}, emitted {}`);
+    }
+    const document = {
+        openapi: '3.1.0',
+        info: config.info,
+        paths,
+        components: { schemas: types.schemas.components, securitySchemes: config.securitySchemes },
+    };
+    if (config.servers.length)
+        document.servers = config.servers;
+    return { document, warnings };
+}

package/build/src/route_types.d.ts

@@ -0,0 +1,25 @@
+import ts from 'typescript';
+import { TypeToSchema } from './type_to_schema.ts';
+import type { RouteOperation } from './types.ts';
+/**
+ * Resolves the request and response types of every route with the app's own
+ * tsconfig, through one in-memory module that names them all.
+ */
+export declare class RouteTypes {
+    #private;
+    readonly checker: ts.TypeChecker;
+    readonly schemas: TypeToSchema;
+    constructor(appRoot: string, routes: RouteOperation[]);
+    /**
+     * The types of one route's `request` and `response` members.
+     */
+    get(routeName: string): {
+        request?: undefined;
+        response?: undefined;
+    } | {
+        request: ts.Type | undefined;
+        response: ts.Type | undefined;
+    };
+    validationError(): ts.Type | undefined;
+    property(type: ts.Type, name: string): ts.Type | undefined;
+}

package/build/src/route_types.js

@@ -0,0 +1,80 @@
+import ts from 'typescript';
+import { join, relative } from 'node:path';
+import { TypeToSchema } from "./type_to_schema.js";
+/**
+ * Resolves the request and response types of every route with the app's own
+ * tsconfig, through one in-memory module that names them all.
+ */
+export class RouteTypes {
+    checker;
+    schemas;
+    #routes;
+    #validationError;
+    constructor(appRoot, routes) {
+        const entryFile = join(appRoot, '.adonisjs/openapi/routes.ts');
+        const config = ts.getParsedCommandLineOfConfigFile(join(appRoot, 'tsconfig.json'), {}, {
+            ...ts.sys,
+            onUnRecoverableConfigFileDiagnostic: diagnostic => {
+                throw new Error(ts.flattenDiagnosticMessageText(diagnostic.messageText, '\n'));
+            },
+        });
+        if (!config)
+            throw new Error(`openapi: cannot read ${join(appRoot, 'tsconfig.json')}`);
+        const source = renderEntry(entryFile, appRoot, routes);
+        const host = ts.createCompilerHost(config.options);
+        const getSourceFile = host.getSourceFile.bind(host);
+        host.getSourceFile = (fileName, languageVersion, ...rest) => fileName === entryFile
+            ? ts.createSourceFile(fileName, source, languageVersion)
+            : getSourceFile(fileName, languageVersion, ...rest);
+        const fileExists = host.fileExists.bind(host);
+        host.fileExists = fileName => fileName === entryFile || fileExists(fileName);
+        // The app's own files carry the module augmentations (container bindings, auth guards) the types depend on.
+        const program = ts.createProgram({
+            rootNames: [...config.fileNames, entryFile],
+            options: { ...config.options, noEmit: true },
+            host,
+        });
+        this.checker = program.getTypeChecker();
+        this.schemas = new TypeToSchema(this.checker);
+        const entry = program.getSourceFile(entryFile);
+        this.#routes = entry.statements.find(ts.isInterfaceDeclaration);
+        this.#validationError = entry.statements.find(ts.isTypeAliasDeclaration);
+    }
+    /**
+     * The types of one route's `request` and `response` members.
+     */
+    get(routeName) {
+        const member = this.#routes.members.find((candidate) => ts.isPropertySignature(candidate) &&
+            ts.isStringLiteral(candidate.name) &&
+            candidate.name.text === routeName);
+        if (!member)
+            return {};
+        const type = this.checker.getTypeAtLocation(member);
+        return { request: this.property(type, 'request'), response: this.property(type, 'response') };
+    }
+    validationError() {
+        return this.#validationError && this.checker.getTypeAtLocation(this.#validationError);
+    }
+    property(type, name) {
+        const symbol = this.checker.getPropertyOfType(type, name);
+        return symbol && this.checker.getTypeOfSymbol(symbol);
+    }
+}
+function renderEntry(entryFile, appRoot, routes) {
+    const toRelative = (expression) => expression.replace(/import\('(app\/[^']+?)(\.ts)?'\)/g, (_, path) => {
+        const target = relative(join(entryFile, '..'), join(appRoot, path));
+        return `import('${target}.js')`;
+    });
+    const imports = new Set(routes.flatMap(route => route.imports));
+    const members = routes.map(route => {
+        const request = route.requestType ? `request: ${toRelative(route.requestType)}; ` : '';
+        const response = route.responseType
+            ? `response: Awaited<${toRelative(route.responseType)}>`
+            : '';
+        return `  ${JSON.stringify(route.name)}: { ${request}${response} }`;
+    });
+    const validationError = routes.some(route => route.validator)
+        ? `import type { SimpleError } from '@vinejs/vine/types'\nexport type ValidationError = { errors: SimpleError[] }`
+        : '';
+    return [...imports, validationError, `export interface Routes {\n${members.join('\n')}\n}`].join('\n');
+}

package/build/src/type_to_schema.d.ts

@@ -0,0 +1,17 @@
+import ts from 'typescript';
+import type { JsonSchema } from './types.ts';
+/**
+ * Converts a type the checker resolved into JSON Schema (draft 2020-12, as OpenAPI 3.1 uses).
+ * Serialized output types are plain data, so methods are dropped and dates become strings.
+ */
+export declare class TypeToSchema {
+    #private;
+    readonly components: Record<string, JsonSchema>;
+    readonly unsupported: Set<string>;
+    constructor(checker: ts.TypeChecker);
+    convert(type: ts.Type, stack?: ts.Type[]): JsonSchema;
+    /**
+     * Whether `undefined` is one of the members, which makes an object property optional.
+     */
+    acceptsUndefined(type: ts.Type): boolean;
+}

package/build/src/type_to_schema.js

@@ -0,0 +1,135 @@
+import ts from 'typescript';
+const OMITTED = ts.TypeFlags.Undefined | ts.TypeFlags.Void;
+// `vine.file()` infers `MultipartFile` on the server and `File | Blob` for clients.
+const BINARY = new Set(['MultipartFile', 'File', 'Blob']);
+/**
+ * Converts a type the checker resolved into JSON Schema (draft 2020-12, as OpenAPI 3.1 uses).
+ * Serialized output types are plain data, so methods are dropped and dates become strings.
+ */
+export class TypeToSchema {
+    #checker;
+    #recursive = new Map();
+    components = {};
+    unsupported = new Set();
+    constructor(checker) {
+        this.#checker = checker;
+    }
+    convert(type, stack = []) {
+        const flags = type.flags;
+        if (flags & (ts.TypeFlags.Any | ts.TypeFlags.Unknown))
+            return {};
+        if (flags & ts.TypeFlags.Never)
+            return { not: {} };
+        if (type.isStringLiteral())
+            return { type: 'string', const: type.value };
+        if (type.isNumberLiteral())
+            return { type: 'number', const: type.value };
+        if (flags & ts.TypeFlags.BooleanLiteral)
+            return { type: 'boolean', const: this.#checker.typeToString(type) === 'true' };
+        if (flags & (ts.TypeFlags.String | ts.TypeFlags.TemplateLiteral))
+            return { type: 'string' };
+        if (flags & ts.TypeFlags.Number)
+            return { type: 'number' };
+        if (flags & ts.TypeFlags.BigInt)
+            return { type: 'integer' };
+        if (flags & ts.TypeFlags.Boolean)
+            return { type: 'boolean' };
+        if (flags & ts.TypeFlags.Null)
+            return { type: 'null' };
+        if (flags & OMITTED)
+            return { not: {} };
+        if (type.isUnion())
+            return this.#union(type, stack);
+        const name = (type.aliasSymbol ?? type.getSymbol())?.getName();
+        if (name === 'Date' || name === 'DateTime')
+            return { type: 'string', format: 'date-time' };
+        if (name && BINARY.has(name))
+            return { type: 'string', format: 'binary' };
+        if (this.#checker.isArrayType(type)) {
+            // SAFETY: isArrayType only holds for TypeReference instances.
+            const [item] = this.#checker.getTypeArguments(type);
+            return { type: 'array', items: item ? this.convert(item, stack) : {} };
+        }
+        if (this.#checker.isTupleType(type)) {
+            // SAFETY: isTupleType only holds for TypeReference instances.
+            const items = this.#checker
+                .getTypeArguments(type)
+                .map(item => this.convert(item, stack));
+            return { type: 'array', prefixItems: items, minItems: items.length, maxItems: items.length };
+        }
+        if (flags & ts.TypeFlags.Object || type.isIntersection())
+            return this.#object(type, name, stack);
+        this.unsupported.add(this.#checker.typeToString(type));
+        return {};
+    }
+    /**
+     * Whether `undefined` is one of the members, which makes an object property optional.
+     */
+    acceptsUndefined(type) {
+        return type.isUnion()
+            ? type.types.some(member => member.flags & OMITTED)
+            : Boolean(type.flags & OMITTED);
+    }
+    #union(type, stack) {
+        const members = type.types.filter(member => !(member.flags & OMITTED));
+        const booleans = members.filter(member => member.flags & ts.TypeFlags.BooleanLiteral);
+        const converted = members
+            .filter(member => !(member.flags & ts.TypeFlags.BooleanLiteral))
+            .map(member => this.convert(member, stack));
+        if (booleans.length === 2)
+            converted.push({ type: 'boolean' });
+        else
+            converted.push(...booleans.map(member => this.convert(member, stack)));
+        const schemas = [...new Map(converted.map(schema => [JSON.stringify(schema), schema])).values()];
+        if (schemas.length === 1)
+            return schemas[0];
+        if (schemas.every(schema => 'const' in schema || schema.type === 'null')) {
+            const types = [...new Set(schemas.flatMap(schema => schema.type ?? []))];
+            return {
+                type: types.length === 1 ? types[0] : types,
+                enum: schemas.map(schema => schema.const ?? null),
+            };
+        }
+        return { anyOf: schemas };
+    }
+    #object(type, name, stack) {
+        if (stack.includes(type))
+            return { $ref: `#/components/schemas/${this.#recursiveName(type, name)}` };
+        const next = [...stack, type];
+        const properties = {};
+        const required = [];
+        for (const property of this.#checker.getPropertiesOfType(type)) {
+            const propertyType = this.#checker.getTypeOfSymbol(property);
+            if (propertyType.getCallSignatures().length)
+                continue;
+            properties[property.getName()] = this.convert(propertyType, next);
+            const optional = property.flags & ts.SymbolFlags.Optional || this.acceptsUndefined(propertyType);
+            if (!optional)
+                required.push(property.getName());
+        }
+        const [index] = this.#checker.getIndexInfosOfType(type);
+        const schema = {
+            type: 'object',
+            properties,
+            additionalProperties: index ? this.convert(index.type, next) : false,
+        };
+        if (required.length)
+            schema.required = required;
+        const ref = this.#recursive.get(type);
+        if (ref) {
+            this.components[ref] = schema;
+            return { $ref: `#/components/schemas/${ref}` };
+        }
+        return schema;
+    }
+    #recursiveName(type, name) {
+        const existing = this.#recursive.get(type);
+        if (existing)
+            return existing;
+        const base = name && !name.startsWith('__') ? name : 'Recursive';
+        const ref = this.components[base] ? `${base}${this.#recursive.size}` : base;
+        this.#recursive.set(type, ref);
+        this.components[ref] = {};
+        return ref;
+    }
+}

package/build/src/types.d.ts

@@ -0,0 +1,114 @@
+export type JsonValue = string | number | boolean | null;
+/**
+ * The JSON Schema keywords the generator reads or writes. Keywords Vine adds
+ * (`minLength`, `pattern`...) pass through untouched.
+ */
+export interface JsonSchema {
+    $ref?: string;
+    type?: string | string[];
+    format?: string;
+    const?: JsonValue;
+    enum?: JsonValue[];
+    properties?: Record<string, JsonSchema>;
+    required?: string[];
+    additionalProperties?: boolean | JsonSchema;
+    items?: JsonSchema;
+    prefixItems?: JsonSchema[];
+    minItems?: number;
+    maxItems?: number;
+    anyOf?: JsonSchema[];
+    not?: JsonSchema;
+}
+export type RouteMatcher = string | RegExp | ((routeName: string) => boolean);
+export type SecurityScheme = {
+    type: 'http';
+    scheme: 'bearer' | 'basic';
+    bearerFormat?: string;
+    description?: string;
+} | {
+    type: 'apiKey';
+    name: string;
+    in: 'header' | 'query' | 'cookie';
+    description?: string;
+};
+export interface OpenApiConfig {
+    /**
+     * Where the document is written, relative to the app root.
+     */
+    output: string;
+    info: {
+        title: string;
+        version: string;
+        description?: string;
+    };
+    servers: {
+        url: string;
+        description?: string;
+    }[];
+    /**
+     * Same filters as Tuyau's `generateRegistry({ routes })`. Only one of them can be set.
+     */
+    routes: {
+        only?: RouteMatcher[];
+        except?: RouteMatcher[];
+    };
+    securitySchemes: Record<string, SecurityScheme>;
+    /**
+     * Maps a named middleware (as in `middleware.auth()`) to a key of `securitySchemes`.
+     */
+    middlewareSecurity: Record<string, string>;
+}
+export type HttpMethod = 'get' | 'post' | 'put' | 'patch' | 'delete' | 'options';
+/**
+ * One named route as the generator sees it: where it lives, and the TypeScript
+ * expressions the routes scanner extracted for its input and output.
+ */
+export interface RouteOperation {
+    name: string;
+    methods: HttpMethod[];
+    path: string;
+    pathParams: string[];
+    middleware: string[];
+    requestType?: string;
+    responseType?: string;
+    imports: string[];
+    validator?: {
+        specifier: string;
+        exportName: string;
+    };
+}
+export interface OpenApiParameter {
+    name: string;
+    in: 'path' | 'query';
+    required: boolean;
+    schema: JsonSchema;
+}
+export interface OpenApiResponse {
+    description: string;
+    content?: Record<string, {
+        schema: JsonSchema;
+    }>;
+}
+export interface OpenApiOperation {
+    operationId: string;
+    tags: string[];
+    parameters?: OpenApiParameter[];
+    requestBody?: {
+        required: true;
+        content: Record<string, {
+            schema: JsonSchema;
+        }>;
+    };
+    responses: Record<string, OpenApiResponse>;
+    security?: Record<string, string[]>[];
+}
+export interface OpenApiDocument {
+    openapi: '3.1.0';
+    info: OpenApiConfig['info'];
+    servers?: OpenApiConfig['servers'];
+    paths: Record<string, Partial<Record<HttpMethod, OpenApiOperation>>>;
+    components: {
+        schemas: Record<string, JsonSchema>;
+        securitySchemes: OpenApiConfig['securitySchemes'];
+    };
+}

package/build/src/types.js

@@ -0,0 +1 @@
+export {};

package/build/stubs/config/openapi.stub

@@ -0,0 +1,15 @@
+{{{
+  exports({ to: app.configPath('openapi.ts') })
+}}}
+import { defineConfig } from '@enzopita/adonisjs-openapi'
+
+export default defineConfig({
+  output: 'openapi.json',
+  info: { title: 'API', version: '1.0.0' },
+  securitySchemes: {
+    accessToken: { type: 'http', scheme: 'bearer' },
+  },
+  middlewareSecurity: {
+    auth: 'accessToken',
+  },
+})

package/build/stubs/main.d.ts

@@ -0,0 +1 @@
+export declare const stubsRoot: string;

package/build/stubs/main.js

@@ -0,0 +1 @@
+export const stubsRoot = import.meta.dirname;

package/package.json

@@ -1,6 +1,58 @@
 {
   "name": "@enzopita/adonisjs-openapi",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "Generate an OpenAPI document from the routes, validators and transformers of an AdonisJS app",
+  "keywords": [
+    "adonisjs",
+    "openapi",
+    "swagger",
+    "tuyau",
+    "vinejs"
+  ],
+  "license": "MIT",
+  "author": "Enzo Pita <enzo@enzopita.com>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/enzopita/adonisjs-packages.git",
+    "directory": "packages/openapi"
+  },
+  "files": [
+    "build",
+    "!build/bin",
+    "!build/tests"
+  ],
+  "type": "module",
+  "exports": {
+    ".": "./build/index.js",
+    "./commands": "./build/commands/main.js",
+    "./types": "./build/src/types.js"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "typescript": "~6.0.3"
+  },
+  "devDependencies": {
+    "@adonisjs/assembler": "^8.5.2",
+    "@adonisjs/core": "^7.6.0",
+    "@adonisjs/tsconfig": "^2.0.0",
+    "@japa/assert": "^4.2.0",
+    "@japa/runner": "^5.3.0",
+    "@poppinss/ts-exec": "^1.4.4",
+    "@types/node": "~26.6.5",
+    "@vinejs/vine": "^4.4.0"
+  },
+  "peerDependencies": {
+    "@adonisjs/assembler": "^8.5.0",
+    "@adonisjs/core": "^7.6.0"
+  },
+  "engines": {
+    "node": ">=24.0.0"
+  },
+  "scripts": {
+    "build": "rm -rf build && tsc -p tsconfig.build.json && cp -r stubs/config build/stubs/",
+    "test": "pnpm run build && node --import=@poppinss/ts-exec --enable-source-maps bin/test.ts",
+    "typecheck": "tsc --noEmit"
+  }
 }