@enzopita/adonisjs-openapi 0.0.0-stage → 0.2.0

package/build/src/type_to_schema.js

@@ -0,0 +1,157 @@
+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();
+    #named;
+    #namesBySchema = new Map();
+    components = {};
+    unsupported = new Set();
+    /**
+     * Every named type becomes a component up front: a transformer nested in another
+     * resolves to a different type than its `Data` alias, and is matched by its schema.
+     */
+    constructor(checker, named = new Map()) {
+        this.#checker = checker;
+        this.#named = named;
+        for (const [type, name] of named) {
+            const schema = this.#properties(type, []);
+            const serialized = JSON.stringify(schema);
+            this.components[name] = schema;
+            if (!this.#namesBySchema.has(serialized))
+                this.#namesBySchema.set(serialized, name);
+        }
+    }
+    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) {
+        const named = this.#named.get(type);
+        if (named)
+            return { $ref: `#/components/schemas/${named}` };
+        if (stack.includes(type))
+            return { $ref: `#/components/schemas/${this.#recursiveName(type, name)}` };
+        const schema = this.#properties(type, stack);
+        const ref = this.#recursive.get(type);
+        if (ref) {
+            this.components[ref] = schema;
+            return { $ref: `#/components/schemas/${ref}` };
+        }
+        const shared = this.#namesBySchema.get(JSON.stringify(schema));
+        return shared ? { $ref: `#/components/schemas/${shared}` } : schema;
+    }
+    #properties(type, stack) {
+        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;
+        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,206 @@
+import type { HttpContext } from '@adonisjs/core/http';
+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;
+        summary?: string;
+        description?: string;
+        termsOfService?: string;
+        contact?: {
+            name?: string;
+            url?: string;
+            email?: string;
+        };
+        license?: {
+            name: string;
+            url?: string;
+            identifier?: string;
+        };
+    };
+    servers: {
+        url: string;
+        description?: string;
+    }[];
+    /**
+     * Written as the document's top-level `tags`, to describe and order the tags operations use.
+     */
+    tags: {
+        name: 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;
+    };
+    controller?: {
+        path: string;
+        method: 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;
+    summary?: string;
+    description?: string;
+    tags: string[];
+    deprecated?: true;
+    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'];
+    tags?: OpenApiConfig['tags'];
+    paths: Record<string, Partial<Record<HttpMethod, OpenApiOperation>>>;
+    components: {
+        schemas: Record<string, JsonSchema>;
+        securitySchemes: OpenApiConfig['securitySchemes'];
+    };
+}
+/**
+ * What a docs UI needs to render its page.
+ */
+export interface DocsPage {
+    title: string;
+    /**
+     * Relative to the page, so the page keeps working behind a proxy that adds a path prefix.
+     */
+    documentUrl: string;
+    /**
+     * The CSP nonce Shield sets on the response, when CSP is enabled.
+     */
+    nonce?: string;
+}
+export type Json = JsonValue | Json[] | {
+    [key: string]: Json;
+};
+/**
+ * Serialized as JSON into the UI's own init call.
+ */
+export type UiOptions = {
+    [key: string]: Json;
+};
+export type DocsUi = {
+    ui?: 'scalar';
+    uiOptions?: UiOptions;
+    cdn?: {
+        script?: string;
+    };
+} | {
+    ui: 'swagger-ui';
+    uiOptions?: UiOptions;
+    cdn?: {
+        script?: string;
+        style?: string;
+    };
+} | {
+    ui: 'redoc';
+    uiOptions?: UiOptions;
+    cdn?: {
+        script?: string;
+    };
+} | {
+    ui: (page: DocsPage) => string;
+    uiOptions?: never;
+    cdn?: never;
+};
+export type DocsOptions = DocsUi & {
+    /**
+     * Path of the page. The document is served at `<prefix>/openapi.json`.
+     */
+    prefix?: string;
+    title?: string;
+    /**
+     * `live` generates the document on each request and needs the app's TypeScript
+     * sources. `file` serves the file `node ace openapi:generate` wrote.
+     */
+    source?: 'live' | 'file';
+    /**
+     * The file `source: 'file'` reads, relative to the app root. Defaults to the config `output`.
+     */
+    file?: string;
+    transform?: (document: OpenApiDocument, ctx: HttpContext) => OpenApiDocument | Promise<OpenApiDocument>;
+};

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,60 @@
 {
   "name": "@enzopita/adonisjs-openapi",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.2.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",
+    "./routes": "./build/src/docs/routes.js",
+    "./build_hook": "./build/src/build_hook.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"
+  }
 }