@jsango/openapi 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 JSango contributors
+
+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

@@ -0,0 +1,29 @@
+# @jsango/openapi
+
+> Deterministic, zero-reflection OpenAPI 3.1.0 document generator and schema adapters for router, validation, ORM, and Admin.
+
+Part of the **[jsango](https://github.com/jsango/jsango)** backend framework for TypeScript.
+
+## Installation
+
+```bash
+pnpm add @jsango/openapi
+```
+
+## Usage
+
+```typescript
+import { OpenApiRegistry, OpenApiFormatter } from '@jsango/openapi';
+
+const registry = new OpenApiRegistry({ title: 'My API', version: '1.0.0' });
+const spec = registry.generateDocument();
+const json = OpenApiFormatter.toJson(spec);
+```
+
+## Documentation
+
+For full architecture documentation and guides, visit the [jsango documentation](https://github.com/jsango/jsango/tree/main/docs).
+
+## License
+
+MIT © jsango contributors

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export * from './public/index.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,mBAAmB,CAAC"}

package/dist/index.js

@@ -0,0 +1,2 @@
+export * from './public/index.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,mBAAmB,CAAC"}

package/dist/public/admin-adapter.d.ts

@@ -0,0 +1,26 @@
+import type { OpenApiPaths } from './types.js';
+export interface AdminFieldDescriptor {
+    readonly name: string;
+    readonly type: string;
+    readonly label?: string | undefined;
+    readonly readonly?: boolean | undefined;
+    readonly required?: boolean | undefined;
+}
+export interface AdminResourceDescriptor {
+    readonly id: string;
+    readonly label: string;
+    readonly pluralLabel?: string | undefined;
+    readonly primaryKey?: string | undefined;
+    readonly listFields?: readonly string[] | undefined;
+    readonly createFields?: readonly string[] | undefined;
+    readonly editFields?: readonly string[] | undefined;
+    readonly searchFields?: readonly string[] | undefined;
+    readonly fields: readonly AdminFieldDescriptor[];
+}
+export declare class AdminAdapter {
+    /**
+     * Generates OpenAPI paths for an Admin resource with explicit 'Admin: <Resource>' tagging.
+     */
+    static generateResourcePaths(resource: AdminResourceDescriptor, prefix?: string): OpenApiPaths;
+}
+//# sourceMappingURL=admin-adapter.d.ts.map

package/dist/public/admin-adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"admin-adapter.d.ts","sourceRoot":"","sources":["../../src/public/admin-adapter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAmC,MAAM,YAAY,CAAC;AAGhF,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACpC,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IACxC,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;CACzC;AAED,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1C,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACzC,QAAQ,CAAC,UAAU,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,CAAC;IACpD,QAAQ,CAAC,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,CAAC;IACtD,QAAQ,CAAC,UAAU,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,CAAC;IACpD,QAAQ,CAAC,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,CAAC;IACtD,QAAQ,CAAC,MAAM,EAAE,SAAS,oBAAoB,EAAE,CAAC;CAClD;AAED,qBAAa,YAAY;IACvB;;OAEG;WACW,qBAAqB,CACjC,QAAQ,EAAE,uBAAuB,EACjC,MAAM,SAAkB,GACvB,YAAY;CAyHhB"}

package/dist/public/admin-adapter.js

@@ -0,0 +1,120 @@
+import { SchemaBuilder } from './schema-builder.js';
+export class AdminAdapter {
+    /**
+     * Generates OpenAPI paths for an Admin resource with explicit 'Admin: <Resource>' tagging.
+     */
+    static generateResourcePaths(resource, prefix = '/admin/api/v1') {
+        const paths = {};
+        const tag = `Admin: ${resource.pluralLabel ?? resource.label}`;
+        const pk = resource.primaryKey ?? 'id';
+        const basePath = `${prefix}/resources/${resource.id}`;
+        const itemPath = `${basePath}/{${pk}}`;
+        const modelSchema = {
+            type: 'object',
+            properties: Object.fromEntries(resource.fields.map((f) => [f.name, { type: 'string', description: f.label ?? f.name }])),
+        };
+        const queryParams = [
+            { name: 'page', in: 'query', schema: { type: 'integer', default: 1 } },
+            { name: 'pageSize', in: 'query', schema: { type: 'integer', default: 25 } },
+            { name: 'search', in: 'query', schema: { type: 'string' } },
+            { name: 'sort', in: 'query', schema: { type: 'string' } },
+            { name: 'sortDirection', in: 'query', schema: { type: 'string', enum: ['asc', 'desc'] } },
+        ];
+        // List & Create Path
+        paths[basePath] = {
+            get: {
+                tags: [tag],
+                summary: `List ${resource.pluralLabel ?? resource.label}`,
+                operationId: `admin_list_${resource.id}`,
+                parameters: queryParams,
+                responses: {
+                    '200': {
+                        description: 'Paginated list of records',
+                        content: {
+                            'application/json': {
+                                schema: SchemaBuilder.paginated(modelSchema),
+                            },
+                        },
+                    },
+                    '403': { description: 'Forbidden — Staff access required' },
+                },
+            },
+            post: {
+                tags: [tag],
+                summary: `Create a ${resource.label}`,
+                operationId: `admin_create_${resource.id}`,
+                requestBody: {
+                    required: true,
+                    content: {
+                        'application/json': {
+                            schema: modelSchema,
+                        },
+                    },
+                },
+                responses: {
+                    '201': {
+                        description: `${resource.label} created successfully`,
+                        content: { 'application/json': { schema: modelSchema } },
+                    },
+                    '403': { description: 'Forbidden — Create permission required' },
+                    '422': { description: 'Validation error' },
+                },
+            },
+        };
+        // Detail, Update, Delete Path
+        const pkParam = {
+            name: pk,
+            in: 'path',
+            required: true,
+            schema: { type: 'string' },
+            description: `Primary key of the ${resource.label}`,
+        };
+        paths[itemPath] = {
+            get: {
+                tags: [tag],
+                summary: `Get ${resource.label} by ID`,
+                operationId: `admin_get_${resource.id}`,
+                parameters: [pkParam],
+                responses: {
+                    '200': {
+                        description: `${resource.label} details`,
+                        content: { 'application/json': { schema: modelSchema } },
+                    },
+                    '404': { description: 'Record not found' },
+                },
+            },
+            patch: {
+                tags: [tag],
+                summary: `Update ${resource.label}`,
+                operationId: `admin_update_${resource.id}`,
+                parameters: [pkParam],
+                requestBody: {
+                    required: true,
+                    content: {
+                        'application/json': { schema: modelSchema },
+                    },
+                },
+                responses: {
+                    '200': {
+                        description: `${resource.label} updated successfully`,
+                        content: { 'application/json': { schema: modelSchema } },
+                    },
+                    '404': { description: 'Record not found' },
+                    '422': { description: 'Validation error' },
+                },
+            },
+            delete: {
+                tags: [tag],
+                summary: `Delete ${resource.label}`,
+                operationId: `admin_delete_${resource.id}`,
+                parameters: [pkParam],
+                responses: {
+                    '204': { description: `${resource.label} deleted successfully` },
+                    '404': { description: 'Record not found' },
+                },
+            },
+        };
+        return paths;
+    }
+}
+//# sourceMappingURL=admin-adapter.js.map

package/dist/public/admin-adapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"admin-adapter.js","sourceRoot":"","sources":["../../src/public/admin-adapter.ts"],"names":[],"mappings":"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"}

package/dist/public/endpoint.d.ts

@@ -0,0 +1,13 @@
+import type { RouteHandler } from '@jsango/router';
+import type { IRouter } from '@jsango/router';
+import { OpenApiGenerator } from './generator.js';
+export interface OpenApiEndpointOptions {
+    readonly router?: IRouter | undefined;
+    readonly format?: 'json' | 'yaml' | 'auto' | undefined;
+    readonly cacheDocument?: boolean | undefined;
+}
+/**
+ * Creates an HTTP RouteHandler that serves the OpenAPI specification document.
+ */
+export declare function createOpenApiHandler(generator: OpenApiGenerator, options?: OpenApiEndpointOptions): RouteHandler;
+//# sourceMappingURL=endpoint.d.ts.map

package/dist/public/endpoint.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"endpoint.d.ts","sourceRoot":"","sources":["../../src/public/endpoint.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AACnD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,gBAAgB,CAAC;AAI9C,OAAO,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAGlD,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IACtC,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;IACvD,QAAQ,CAAC,aAAa,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;CAC9C;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAClC,SAAS,EAAE,gBAAgB,EAC3B,OAAO,GAAE,sBAA2B,GACnC,YAAY,CAqCd"}

package/dist/public/endpoint.js

@@ -0,0 +1,38 @@
+import { HttpResponse, HttpStatus, ContentType } from '@jsango/http';
+import { OpenApiFormatter } from './formatter.js';
+/**
+ * Creates an HTTP RouteHandler that serves the OpenAPI specification document.
+ */
+export function createOpenApiHandler(generator, options = {}) {
+    let cachedJson;
+    let cachedYaml;
+    return (ctx) => {
+        const targetRouter = options.router;
+        const reqFormat = ctx.request.query.get('format')?.toLowerCase();
+        const accept = ctx.request.headers.get('accept')?.toLowerCase() ?? '';
+        const isYaml = reqFormat === 'yaml' ||
+            options.format === 'yaml' ||
+            (options.format === 'auto' &&
+                (accept.includes('application/yaml') || accept.includes('text/yaml')));
+        if (isYaml) {
+            if (!cachedYaml || !options.cacheDocument) {
+                const doc = generator.generate(targetRouter);
+                cachedYaml = OpenApiFormatter.toYaml(doc);
+            }
+            return new HttpResponse(cachedYaml, {
+                status: HttpStatus.OK,
+                headers: { 'content-type': 'application/yaml; charset=utf-8' },
+            });
+        }
+        // Default JSON
+        if (!cachedJson || !options.cacheDocument) {
+            const doc = generator.generate(targetRouter);
+            cachedJson = OpenApiFormatter.toJson(doc, true);
+        }
+        return new HttpResponse(cachedJson, {
+            status: HttpStatus.OK,
+            headers: { 'content-type': `${ContentType.JSON}; charset=utf-8` },
+        });
+    };
+}
+//# sourceMappingURL=endpoint.js.map

package/dist/public/endpoint.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"endpoint.js","sourceRoot":"","sources":["../../src/public/endpoint.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAGrE,OAAO,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAQlD;;GAEG;AACH,MAAM,UAAU,oBAAoB,CAClC,SAA2B,EAC3B,UAAkC,EAAE;IAEpC,IAAI,UAA8B,CAAC;IACnC,IAAI,UAA8B,CAAC;IAEnC,OAAO,CAAC,GAAmB,EAAE,EAAE;QAC7B,MAAM,YAAY,GAAG,OAAO,CAAC,MAAM,CAAC;QACpC,MAAM,SAAS,GAAG,GAAG,CAAC,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,QAAQ,CAAC,EAAE,WAAW,EAAE,CAAC;QACjE,MAAM,MAAM,GAAG,GAAG,CAAC,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAC,EAAE,WAAW,EAAE,IAAI,EAAE,CAAC;QAEtE,MAAM,MAAM,GACV,SAAS,KAAK,MAAM;YACpB,OAAO,CAAC,MAAM,KAAK,MAAM;YACzB,CAAC,OAAO,CAAC,MAAM,KAAK,MAAM;gBACxB,CAAC,MAAM,CAAC,QAAQ,CAAC,kBAAkB,CAAC,IAAI,MAAM,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC;QAE3E,IAAI,MAAM,EAAE,CAAC;YACX,IAAI,CAAC,UAAU,IAAI,CAAC,OAAO,CAAC,aAAa,EAAE,CAAC;gBAC1C,MAAM,GAAG,GAAoB,SAAS,CAAC,QAAQ,CAAC,YAAY,CAAC,CAAC;gBAC9D,UAAU,GAAG,gBAAgB,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YAC5C,CAAC;YACD,OAAO,IAAI,YAAY,CAAC,UAAU,EAAE;gBAClC,MAAM,EAAE,UAAU,CAAC,EAAE;gBACrB,OAAO,EAAE,EAAE,cAAc,EAAE,iCAAiC,EAAE;aAC/D,CAAC,CAAC;QACL,CAAC;QAED,eAAe;QACf,IAAI,CAAC,UAAU,IAAI,CAAC,OAAO,CAAC,aAAa,EAAE,CAAC;YAC1C,MAAM,GAAG,GAAoB,SAAS,CAAC,QAAQ,CAAC,YAAY,CAAC,CAAC;YAC9D,UAAU,GAAG,gBAAgB,CAAC,MAAM,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;QAClD,CAAC;QAED,OAAO,IAAI,YAAY,CAAC,UAAU,EAAE;YAClC,MAAM,EAAE,UAAU,CAAC,EAAE;YACrB,OAAO,EAAE,EAAE,cAAc,EAAE,GAAG,WAAW,CAAC,IAAI,iBAAiB,EAAE;SAClE,CAAC,CAAC;IACL,CAAC,CAAC;AACJ,CAAC"}

package/dist/public/errors.d.ts

@@ -0,0 +1,15 @@
+import { JsangoError } from '@jsango/core';
+export declare class OpenApiError extends JsangoError {
+    constructor(message: string, code?: string, meta?: Record<string, unknown>);
+}
+export declare class DuplicateOperationIdError extends OpenApiError {
+    constructor(operationId: string, pathA: string, methodA: string, pathB: string, methodB: string);
+}
+export declare class ConflictingSchemaError extends OpenApiError {
+    constructor(name: string, reason: string);
+}
+export declare class InvalidOpenApiDocumentError extends OpenApiError {
+    readonly validationErrors: readonly string[];
+    constructor(errors: readonly string[]);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/public/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/public/errors.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAE3C,qBAAa,YAAa,SAAQ,WAAW;gBAC/B,OAAO,EAAE,MAAM,EAAE,IAAI,SAAwB,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;CAI1F;AAED,qBAAa,yBAA0B,SAAQ,YAAY;gBAC7C,WAAW,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM;CAYhG;AAED,qBAAa,sBAAuB,SAAQ,YAAY;gBAC1C,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM;CAQzC;AAED,qBAAa,2BAA4B,SAAQ,YAAY;IAC3D,SAAgB,gBAAgB,EAAE,SAAS,MAAM,EAAE,CAAC;gBAExC,MAAM,EAAE,SAAS,MAAM,EAAE;CAStC"}

package/dist/public/errors.js

@@ -0,0 +1,32 @@
+import { JsangoError } from '@jsango/core';
+export class OpenApiError extends JsangoError {
+    constructor(message, code = 'ERR_OPENAPI_GENERAL', meta) {
+        super({ code, message, metadata: meta });
+        this.name = 'OpenApiError';
+    }
+}
+export class DuplicateOperationIdError extends OpenApiError {
+    constructor(operationId, pathA, methodA, pathB, methodB) {
+        super(`Duplicate operationId "${operationId}" detected across ${methodA} ${pathA} and ${methodB} ${pathB}.`, 'ERR_OPENAPI_DUPLICATE_OPERATION_ID', {
+            operationId,
+            first: { path: pathA, method: methodA },
+            second: { path: pathB, method: methodB },
+        });
+        this.name = 'DuplicateOperationIdError';
+    }
+}
+export class ConflictingSchemaError extends OpenApiError {
+    constructor(name, reason) {
+        super(`Incompatible schema definition registered for component schema "${name}": ${reason}`, 'ERR_OPENAPI_CONFLICTING_SCHEMA', { schemaName: name, reason });
+        this.name = 'ConflictingSchemaError';
+    }
+}
+export class InvalidOpenApiDocumentError extends OpenApiError {
+    validationErrors;
+    constructor(errors) {
+        super(`OpenAPI Document validation failed:\n - ${errors.join('\n - ')}`, 'ERR_OPENAPI_INVALID_DOCUMENT', { errors });
+        this.name = 'InvalidOpenApiDocumentError';
+        this.validationErrors = errors;
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/public/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/public/errors.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAE3C,MAAM,OAAO,YAAa,SAAQ,WAAW;IAC3C,YAAY,OAAe,EAAE,IAAI,GAAG,qBAAqB,EAAE,IAA8B;QACvF,KAAK,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC;QACzC,IAAI,CAAC,IAAI,GAAG,cAAc,CAAC;IAC7B,CAAC;CACF;AAED,MAAM,OAAO,yBAA0B,SAAQ,YAAY;IACzD,YAAY,WAAmB,EAAE,KAAa,EAAE,OAAe,EAAE,KAAa,EAAE,OAAe;QAC7F,KAAK,CACH,0BAA0B,WAAW,qBAAqB,OAAO,IAAI,KAAK,QAAQ,OAAO,IAAI,KAAK,GAAG,EACrG,oCAAoC,EACpC;YACE,WAAW;YACX,KAAK,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE;YACvC,MAAM,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE;SACzC,CACF,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,2BAA2B,CAAC;IAC1C,CAAC;CACF;AAED,MAAM,OAAO,sBAAuB,SAAQ,YAAY;IACtD,YAAY,IAAY,EAAE,MAAc;QACtC,KAAK,CACH,mEAAmE,IAAI,MAAM,MAAM,EAAE,EACrF,gCAAgC,EAChC,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,EAAE,CAC7B,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,wBAAwB,CAAC;IACvC,CAAC;CACF;AAED,MAAM,OAAO,2BAA4B,SAAQ,YAAY;IAC3C,gBAAgB,CAAoB;IAEpD,YAAY,MAAyB;QACnC,KAAK,CACH,2CAA2C,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,EACjE,8BAA8B,EAC9B,EAAE,MAAM,EAAE,CACX,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,6BAA6B,CAAC;QAC1C,IAAI,CAAC,gBAAgB,GAAG,MAAM,CAAC;IACjC,CAAC;CACF"}

package/dist/public/formatter.d.ts

@@ -0,0 +1,13 @@
+import type { OpenApiDocument } from './types.js';
+export declare class OpenApiFormatter {
+    /**
+     * Formats the document as JSON string.
+     */
+    static toJson(doc: OpenApiDocument, pretty?: boolean): string;
+    /**
+     * Formats the document as a clean YAML string with zero external dependencies.
+     */
+    static toYaml(doc: OpenApiDocument): string;
+    private static serializeYamlValue;
+}
+//# sourceMappingURL=formatter.d.ts.map

package/dist/public/formatter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"formatter.d.ts","sourceRoot":"","sources":["../../src/public/formatter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAElD,qBAAa,gBAAgB;IAC3B;;OAEG;WACW,MAAM,CAAC,GAAG,EAAE,eAAe,EAAE,MAAM,UAAO,GAAG,MAAM;IAIjE;;OAEG;WACW,MAAM,CAAC,GAAG,EAAE,eAAe,GAAG,MAAM;IAIlD,OAAO,CAAC,MAAM,CAAC,kBAAkB;CAqElC"}

package/dist/public/formatter.js

@@ -0,0 +1,77 @@
+export class OpenApiFormatter {
+    /**
+     * Formats the document as JSON string.
+     */
+    static toJson(doc, pretty = true) {
+        return JSON.stringify(doc, null, pretty ? 2 : undefined);
+    }
+    /**
+     * Formats the document as a clean YAML string with zero external dependencies.
+     */
+    static toYaml(doc) {
+        return this.serializeYamlValue(doc, 0);
+    }
+    static serializeYamlValue(value, indentLevel) {
+        const indent = '  '.repeat(indentLevel);
+        if (value === null || value === undefined) {
+            return 'null';
+        }
+        if (typeof value === 'boolean' || typeof value === 'number') {
+            return String(value);
+        }
+        if (typeof value === 'string') {
+            // Escape or quote strings with special characters or newlines
+            if (value.includes('\n')) {
+                const lines = value
+                    .split('\n')
+                    .map((l) => `${indent}  ${l}`)
+                    .join('\n');
+                return `|\n${lines}`;
+            }
+            if (value === '' ||
+                /[:#[\]{},&*?|<>=!%@`]/.test(value) ||
+                value === 'true' ||
+                value === 'false' ||
+                value === 'null' ||
+                !isNaN(Number(value))) {
+                return JSON.stringify(value);
+            }
+            return value;
+        }
+        if (Array.isArray(value)) {
+            if (value.length === 0)
+                return '[]';
+            const lines = [];
+            for (const item of value) {
+                if (typeof item === 'object' && item !== null && !Array.isArray(item)) {
+                    const itemYaml = this.serializeYamlValue(item, indentLevel + 1).trimStart();
+                    lines.push(`${indent}- ${itemYaml}`);
+                }
+                else {
+                    lines.push(`${indent}- ${this.serializeYamlValue(item, indentLevel + 1)}`);
+                }
+            }
+            return lines.join('\n');
+        }
+        if (typeof value === 'object') {
+            const entries = Object.entries(value).filter(([, v]) => v !== undefined);
+            if (entries.length === 0)
+                return '{}';
+            const lines = [];
+            for (const [k, v] of entries) {
+                const key = /[:#[\]{},&*?|<>=!%@`]/.test(k) ? JSON.stringify(k) : k;
+                if (typeof v === 'object' &&
+                    v !== null &&
+                    (Array.isArray(v) ? v.length > 0 : Object.keys(v).length > 0)) {
+                    lines.push(`${indent}${key}:\n${this.serializeYamlValue(v, indentLevel + 1)}`);
+                }
+                else {
+                    lines.push(`${indent}${key}: ${this.serializeYamlValue(v, indentLevel + 1)}`);
+                }
+            }
+            return lines.join('\n');
+        }
+        return String(value);
+    }
+}
+//# sourceMappingURL=formatter.js.map

package/dist/public/formatter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"formatter.js","sourceRoot":"","sources":["../../src/public/formatter.ts"],"names":[],"mappings":"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"}

package/dist/public/generator.d.ts

@@ -0,0 +1,37 @@
+import type { IRouter } from '@jsango/router';
+import type { OpenApiDocument, OpenApiInfo, OpenApiVersion, OpenApiServer, OpenApiSecurityRequirement, OpenApiTag } from './types.js';
+import { OpenApiRegistry } from './registry.js';
+export interface OpenApiGeneratorOptions {
+    readonly info: OpenApiInfo;
+    readonly openapi?: OpenApiVersion | undefined;
+    readonly servers?: readonly OpenApiServer[] | undefined;
+    readonly registry?: OpenApiRegistry | undefined;
+    readonly includeAdmin?: boolean | undefined;
+    readonly defaultSecurity?: readonly OpenApiSecurityRequirement[] | undefined;
+    readonly tags?: readonly OpenApiTag[] | undefined;
+}
+export declare class OpenApiGenerator {
+    private readonly info;
+    private readonly version;
+    private readonly servers;
+    private readonly registry;
+    private readonly includeAdmin;
+    private readonly defaultSecurity?;
+    private readonly tags;
+    constructor(options: OpenApiGeneratorOptions);
+    getRegistry(): OpenApiRegistry;
+    /**
+     * Generates a deterministic OpenApiDocument from the router and registry.
+     */
+    generate(router?: IRouter): OpenApiDocument;
+    private shouldSkipRoute;
+    /**
+     * Normalizes router path syntax (`/users/:id<number>`) to OpenAPI syntax (`/users/{id}`)
+     * and derives path parameter definitions from constraints.
+     */
+    private normalizePathAndParams;
+    private generateOperationId;
+    private defaultResponses;
+    private buildComponents;
+}
+//# sourceMappingURL=generator.d.ts.map

package/dist/public/generator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"generator.d.ts","sourceRoot":"","sources":["../../src/public/generator.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAS,MAAM,gBAAgB,CAAC;AACrD,OAAO,KAAK,EACV,eAAe,EACf,WAAW,EACX,cAAc,EACd,aAAa,EAMb,0BAA0B,EAC1B,UAAU,EAEX,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAIhD,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAC3B,QAAQ,CAAC,OAAO,CAAC,EAAE,cAAc,GAAG,SAAS,CAAC;IAC9C,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,aAAa,EAAE,GAAG,SAAS,CAAC;IACxD,QAAQ,CAAC,QAAQ,CAAC,EAAE,eAAe,GAAG,SAAS,CAAC;IAChD,QAAQ,CAAC,YAAY,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IAC5C,QAAQ,CAAC,eAAe,CAAC,EAAE,SAAS,0BAA0B,EAAE,GAAG,SAAS,CAAC;IAC7E,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,UAAU,EAAE,GAAG,SAAS,CAAC;CACnD;AAED,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAc;IACnC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAiB;IACzC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA2B;IACnD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAkB;IAC3C,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAU;IACvC,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAC,CAAoD;IACrF,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAwB;gBAEjC,OAAO,EAAE,uBAAuB;IAqBrC,WAAW,IAAI,eAAe;IAIrC;;OAEG;IACI,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,GAAG,eAAe;IAyGlD,OAAO,CAAC,eAAe;IAiBvB;;;OAGG;IACH,OAAO,CAAC,sBAAsB;IAoC9B,OAAO,CAAC,mBAAmB;IAK3B,OAAO,CAAC,gBAAgB;IAexB,OAAO,CAAC,eAAe;CA+CxB"}