nestjs-openapi-parser 0.0.1

package/dist/parser/schema-builder.js

@@ -0,0 +1,355 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SchemaBuilder = void 0;
+const ts_morph_1 = require("ts-morph");
+const ast_index_1 = require("./ast-index");
+const tags_1 = require("./tags");
+/**
+ * Converts TypeScript classes (entities & DTOs) into OpenAPI `components.schemas`.
+ * Handles:
+ *  - required derived from `@IsOptional()` / `?` (configurable)
+ *  - `@Exclude()` properties omitted (configurable)
+ *  - union object types -> `oneOf`, string-literal unions -> enum
+ *  - `PartialType / PickType / OmitType / IntersectionType` heritage
+ */
+class SchemaBuilder {
+    index;
+    schemas = {};
+    pending = new Set();
+    done = new Set();
+    activeScopes;
+    knownScopes;
+    constructor(index, options = {}) {
+        this.index = index;
+        this.activeScopes = options.activeScopes ?? new Set();
+        this.knownScopes = options.knownScopes;
+    }
+    /** Register a reference to a class schema and return the `$ref` fragment. */
+    registerRef(name) {
+        if (!this.index.hasClass(name))
+            return { type: 'object' };
+        if (!this.done.has(name))
+            this.pending.add(name);
+        return { $ref: `#/components/schemas/${name}` };
+    }
+    /** Process the queue until no schema remains to build. */
+    build() {
+        while (this.pending.size) {
+            const name = this.pending.values().next().value;
+            this.pending.delete(name);
+            if (this.done.has(name))
+                continue;
+            this.done.add(name);
+            const clazz = this.index.getClass(name);
+            if (!clazz)
+                continue;
+            const classScopes = (0, tags_1.getScopes)((0, tags_1.getTags)(clazz));
+            if (!(0, tags_1.isVisible)(classScopes, this.activeScopes)) {
+                throw new Error(`Scope conflict: class "${name}" is reached by the spec but has @Scope ${formatScopes(classScopes)} ` +
+                    `which doesn't match the active scopes ${formatScopes(this.activeScopes)}. ` +
+                    `Add a matching scope to --scope/config.scopes, or hide whatever referenced it.`);
+            }
+            const members = this.buildMembers(clazz);
+            const schema = { type: 'object', properties: members.properties };
+            if (members.required.length)
+                schema.required = members.required;
+            const rawDesc = clazz.getJsDocs()[0]?.getCommentText();
+            const desc = rawDesc
+                ? (0, tags_1.filterScopedComments)(rawDesc, this.activeScopes, {
+                    itemPath: name,
+                    knownScopes: this.knownScopes,
+                })
+                : undefined;
+            if (desc)
+                schema.description = desc;
+            this.schemas[name] = schema;
+        }
+    }
+    getSchemas() {
+        return this.schemas;
+    }
+    /** Public entry to map an arbitrary type to an OpenAPI schema fragment. */
+    typeToSchema(type) {
+        return this.schemaForType(type);
+    }
+    /** Flatten a class's properties (own + inherited / mapped-type heritage). */
+    buildMembers(clazz) {
+        const base = clazz.getBaseClass();
+        let inherited = { properties: {}, required: [] };
+        if (base) {
+            inherited = this.buildMembers(base);
+        }
+        else {
+            const ext = clazz.getExtends();
+            if (ext)
+                inherited = this.resolveHeritage(ext.getExpression());
+        }
+        return this.mergeMembers(inherited, this.buildOwnMembers(clazz));
+    }
+    buildOwnMembers(clazz) {
+        const properties = {};
+        const required = [];
+        const excludeDecorator = this.index.excludeDecorator;
+        for (const prop of clazz.getInstanceProperties()) {
+            if (!ts_morph_1.Node.isPropertyDeclaration(prop))
+                continue;
+            if (prop.getDecorator(excludeDecorator))
+                continue;
+            if (!(0, tags_1.isVisible)((0, tags_1.getScopes)((0, tags_1.getTags)(prop)), this.activeScopes))
+                continue;
+            const name = prop.getName();
+            const schema = this.schemaForType(prop.getType());
+            this.applyValidatorConstraints(schema, prop);
+            const rawDesc = prop.getJsDocs()[0]?.getCommentText();
+            const desc = rawDesc
+                ? (0, tags_1.filterScopedComments)(rawDesc, this.activeScopes, {
+                    itemPath: `${clazz.getName() ?? '<anon>'}.${name}`,
+                    knownScopes: this.knownScopes,
+                })
+                : undefined;
+            properties[name] = desc ? withDescription(schema, desc) : schema;
+            if (!this.index.isOptionalProperty(prop))
+                required.push(name);
+        }
+        return { properties, required };
+    }
+    /** Resolve `PartialType() / PickType() / OmitType() / IntersectionType()` heritage. */
+    resolveHeritage(expr) {
+        if (ts_morph_1.Node.isIdentifier(expr)) {
+            const cls = this.index.getClass(expr.getText());
+            return cls ? this.buildMembers(cls) : { properties: {}, required: [] };
+        }
+        if (ts_morph_1.Node.isCallExpression(expr)) {
+            const fnName = expr.getExpression().getText();
+            const args = expr.getArguments();
+            if (fnName === 'IntersectionType') {
+                let merged = { properties: {}, required: [] };
+                for (const arg of args)
+                    merged = this.mergeMembers(merged, this.resolveHeritage(arg));
+                return merged;
+            }
+            const inner = args.length ? this.resolveHeritage(args[0]) : { properties: {}, required: [] };
+            if (fnName === 'PartialType')
+                return { properties: inner.properties, required: [] };
+            if (fnName === 'PickType')
+                return this.pick(inner, this.parseStringArray(args[1]));
+            if (fnName === 'OmitType')
+                return this.omit(inner, this.parseStringArray(args[1]));
+            return inner;
+        }
+        return { properties: {}, required: [] };
+    }
+    schemaForType(type) {
+        if (type.isString())
+            return { type: 'string' };
+        if (type.isNumber())
+            return { type: 'number' };
+        if (type.isBoolean())
+            return { type: 'boolean' };
+        const symbolName = ast_index_1.AstIndex.symbolName(type);
+        if (symbolName === 'Date')
+            return { type: 'string', format: 'date-time' };
+        if (type.isArray()) {
+            const element = type.getArrayElementType();
+            return { type: 'array', items: element ? this.schemaForType(element) : {} };
+        }
+        if (symbolName && this.index.hasEnum(symbolName)) {
+            return this.enumSchema(symbolName);
+        }
+        if (type.isUnion()) {
+            const members = type.getUnionTypes().filter((t) => !t.isUndefined() && !t.isNull());
+            if (members.length === 1)
+                return this.schemaForType(members[0]);
+            if (members.length && members.every((t) => t.isStringLiteral())) {
+                return { type: 'string', enum: members.map((t) => t.getLiteralValue()) };
+            }
+            const objectMembers = members.filter((t) => {
+                const n = ast_index_1.AstIndex.symbolName(t);
+                return n && this.index.hasClass(n);
+            });
+            if (members.length > 0 && objectMembers.length === members.length) {
+                return { oneOf: members.map((t) => this.registerRef(ast_index_1.AstIndex.symbolName(t))) };
+            }
+            return { type: 'object' };
+        }
+        if (symbolName && this.index.hasClass(symbolName)) {
+            return this.registerRef(symbolName);
+        }
+        return { type: 'object' };
+    }
+    /**
+     * Build the schema for a named TS enum, deriving `type` from the member
+     * values rather than assuming strings:
+     *  - all strings        -> `string`
+     *  - all integers       -> `integer`
+     *  - all numbers (some non-integer) -> `number`
+     *  - mixed string/number -> `type` omitted (no single OpenAPI type fits)
+     */
+    enumSchema(name) {
+        const values = this.index.getEnumValues(name) ?? [];
+        if (values.length === 0)
+            return { type: 'string', enum: values };
+        if (values.every((v) => typeof v === 'number')) {
+            const type = values.every((v) => Number.isInteger(v)) ? 'integer' : 'number';
+            return { type, enum: values };
+        }
+        if (values.every((v) => typeof v === 'string')) {
+            return { type: 'string', enum: values };
+        }
+        return { enum: values };
+    }
+    /**
+     * Merge class-validator constraints from a property's decorators into its
+     * schema. Unknown decorators are ignored. A `$ref` is left untouched (its
+     * siblings are ignored by OpenAPI 3.0, so constraints don't belong on it).
+     *
+     *  - `@Min/@Max`                  -> `minimum` / `maximum`
+     *  - `@MinLength/@MaxLength`      -> `minLength` / `maxLength`
+     *  - `@Length(min, max)`         -> `minLength` + `maxLength`
+     *  - `@ArrayMinSize/@ArrayMaxSize` -> `minItems` / `maxItems`
+     *  - `@IsEmail/@IsUrl/@IsUUID/@IsDateString` -> `format`
+     *  - `@Matches(/re/)`            -> `pattern`
+     *  - `@IsInt`                    -> narrows `number` to `integer`
+     *  - `@IsPositive/@IsNegative`   -> exclusive `minimum` / `maximum` of 0
+     */
+    applyValidatorConstraints(schema, prop) {
+        if ('$ref' in schema)
+            return;
+        for (const decorator of prop.getDecorators()) {
+            const args = decorator.getArguments();
+            const setNum = (key, value) => {
+                if (value !== undefined)
+                    schema[key] = value;
+            };
+            switch (decorator.getName()) {
+                case 'Min':
+                    setNum('minimum', literalNumber(args[0]));
+                    break;
+                case 'Max':
+                    setNum('maximum', literalNumber(args[0]));
+                    break;
+                case 'MinLength':
+                    setNum('minLength', literalNumber(args[0]));
+                    break;
+                case 'MaxLength':
+                    setNum('maxLength', literalNumber(args[0]));
+                    break;
+                case 'Length':
+                    setNum('minLength', literalNumber(args[0]));
+                    setNum('maxLength', literalNumber(args[1]));
+                    break;
+                case 'ArrayMinSize':
+                    setNum('minItems', literalNumber(args[0]));
+                    break;
+                case 'ArrayMaxSize':
+                    setNum('maxItems', literalNumber(args[0]));
+                    break;
+                case 'IsEmail':
+                    schema.format = 'email';
+                    break;
+                case 'IsUrl':
+                    schema.format = 'uri';
+                    break;
+                case 'IsUUID':
+                    schema.format = 'uuid';
+                    break;
+                case 'IsDateString':
+                    schema.format = 'date-time';
+                    break;
+                case 'IsInt':
+                    if (schema.type === 'number')
+                        schema.type = 'integer';
+                    break;
+                case 'IsPositive':
+                    schema.minimum = 0;
+                    schema.exclusiveMinimum = true;
+                    break;
+                case 'IsNegative':
+                    schema.maximum = 0;
+                    schema.exclusiveMaximum = true;
+                    break;
+                case 'Matches': {
+                    const pattern = regexLiteralPattern(args[0]);
+                    if (pattern !== undefined)
+                        schema.pattern = pattern;
+                    break;
+                }
+            }
+        }
+    }
+    mergeMembers(a, b) {
+        const properties = { ...a.properties, ...b.properties };
+        const required = [...new Set([...a.required, ...b.required])].filter((k) => k in properties);
+        return { properties, required };
+    }
+    pick(members, keys) {
+        const properties = {};
+        for (const key of keys)
+            if (key in members.properties)
+                properties[key] = members.properties[key];
+        return { properties, required: members.required.filter((k) => keys.includes(k)) };
+    }
+    omit(members, keys) {
+        const properties = {};
+        for (const key of Object.keys(members.properties)) {
+            if (!keys.includes(key))
+                properties[key] = members.properties[key];
+        }
+        return { properties, required: members.required.filter((k) => !keys.includes(k)) };
+    }
+    parseStringArray(arg) {
+        if (!arg)
+            return [];
+        let node = arg;
+        if (ts_morph_1.Node.isAsExpression(node))
+            node = node.getExpression();
+        if (ts_morph_1.Node.isArrayLiteralExpression(node)) {
+            return node
+                .getElements()
+                .map((el) => ts_morph_1.Node.isStringLiteral(el) ? el.getLiteralValue() : el.getText().replace(/['"]/g, ''));
+        }
+        return [];
+    }
+}
+exports.SchemaBuilder = SchemaBuilder;
+function formatScopes(scopes) {
+    return scopes.size === 0 ? '{}' : `{${[...scopes].join(', ')}}`;
+}
+/** A numeric decorator argument, supporting a leading unary `-`/`+` (e.g. `@Min(-1)`). */
+function literalNumber(arg) {
+    if (!arg)
+        return undefined;
+    if (ts_morph_1.Node.isNumericLiteral(arg))
+        return arg.getLiteralValue();
+    if (ts_morph_1.Node.isPrefixUnaryExpression(arg)) {
+        const operand = arg.getOperand();
+        if (ts_morph_1.Node.isNumericLiteral(operand)) {
+            const value = operand.getLiteralValue();
+            return arg.getOperatorToken() === ts_morph_1.SyntaxKind.MinusToken ? -value : value;
+        }
+    }
+    return undefined;
+}
+/** The pattern of a `@Matches(...)` argument — a regex literal `/re/flags` or a string. */
+function regexLiteralPattern(arg) {
+    if (!arg)
+        return undefined;
+    if (ts_morph_1.Node.isStringLiteral(arg))
+        return arg.getLiteralValue();
+    const match = /^\/(.*)\/[dgimsuy]*$/s.exec(arg.getText());
+    return match ? match[1] : undefined;
+}
+/**
+ * Attach a `description` to a property schema. A `$ref` is a Reference Object
+ * whose sibling keys are ignored in OpenAPI 3.0, so a bare `$ref` is wrapped in
+ * `allOf` (a normal Schema Object) so the description is actually honored. Any
+ * other schema takes the description directly as a sibling.
+ */
+function withDescription(schema, description) {
+    if ('$ref' in schema) {
+        return { allOf: [schema], description };
+    }
+    schema.description = description;
+    return schema;
+}
+//# sourceMappingURL=schema-builder.js.map

package/dist/parser/schema-builder.js.map

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

package/dist/parser/tags.d.ts

@@ -0,0 +1,61 @@
+import type { Node } from 'ts-morph';
+/** Tag name → values (one entry per `@TagName` occurrence in the node's JSDoc). */
+export type TagBag = Record<string, string[]>;
+/**
+ * Extract all custom JSDoc tags on a node.
+ *
+ * Only tags at line start (after the JSDoc `* ` prefix) are recognized — inline
+ * mentions like `Some text with @Scope inline` are description, not tags.
+ * That behavior comes from the TypeScript JSDoc parser; we just consume it.
+ *
+ * The value is taken from the SAME line as `@TagName`. ts-morph treats lines
+ * after a tag as continuation of the tag's body until the next tag, but we
+ * want subsequent comment lines to remain plain description — so we read only
+ * the first line.
+ */
+export declare function getTags(node: Node): TagBag;
+/**
+ * Resolve the `@Scope` tag values on a node into a flat set of scope names.
+ * Accepts comma-separated lists with optional whitespace
+ * (`@Scope internal,admin`, `@Scope internal, admin`) and multiple occurrences
+ * (`@Scope internal` on one line and `@Scope admin` on another).
+ */
+export declare function getScopes(bag: TagBag): Set<string>;
+/**
+ * Decide whether an item is visible under the active scopes.
+ *
+ *  - Untagged items (`itemScopes` empty) are always visible.
+ *  - When no scope is active, only untagged items are visible.
+ *  - Otherwise, visible iff at least one of the item's scopes is active.
+ */
+export declare function isVisible(itemScopes: Set<string>, activeScopes: Set<string>): boolean;
+/**
+ * Normalize an `--scope a,b --scope c` style CLI input (or a `scopes` config
+ * array) into a flat string list — comma-split, trimmed, falsy filtered.
+ */
+export declare function parseScopeList(raw: string | string[] | undefined): string[];
+/**
+ * Filter `<scope>…</scope>` fragments inside a JSDoc description.
+ *
+ *  - Untagged text passes through unchanged.
+ *  - `<X>…</X>` keeps its inner text when `X ∈ activeScopes`; otherwise the
+ *    whole block (open tag → close tag) is removed.
+ *  - The remaining text is normalized: lines that contained only an open/close
+ *    tag are dropped (including their newline), runs of 3+ newlines collapse
+ *    to 2, and the result is trimmed.
+ *  - Nested fragments, mismatched close tags, and unclosed open tags throw.
+ *
+ * Only names that are *known scopes* are treated as fragment delimiters. Pass
+ * the project's scope vocabulary via `ctx.knownScopes`; any other angle-bracket
+ * token — generics in prose (`Array<string>`), placeholders (`<id>`, `<token>`),
+ * inline HTML (`<b>…</b>`) — passes through verbatim and never throws. When
+ * `ctx.knownScopes` is omitted, every `<name>` is treated as a fragment (legacy
+ * behavior, retained for direct callers and unit tests).
+ *
+ * The optional `ctx.itemPath` (e.g. `"User.email"`) is included in the error
+ * message so misconfigured comments are easy to locate.
+ */
+export declare function filterScopedComments(text: string, activeScopes: Set<string>, ctx?: {
+    itemPath?: string;
+    knownScopes?: Set<string>;
+}): string;

package/dist/parser/tags.js

@@ -0,0 +1,163 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getTags = getTags;
+exports.getScopes = getScopes;
+exports.isVisible = isVisible;
+exports.parseScopeList = parseScopeList;
+exports.filterScopedComments = filterScopedComments;
+function hasJsDocs(node) {
+    return typeof node.getJsDocs === 'function';
+}
+/**
+ * Extract all custom JSDoc tags on a node.
+ *
+ * Only tags at line start (after the JSDoc `* ` prefix) are recognized — inline
+ * mentions like `Some text with @Scope inline` are description, not tags.
+ * That behavior comes from the TypeScript JSDoc parser; we just consume it.
+ *
+ * The value is taken from the SAME line as `@TagName`. ts-morph treats lines
+ * after a tag as continuation of the tag's body until the next tag, but we
+ * want subsequent comment lines to remain plain description — so we read only
+ * the first line.
+ */
+function getTags(node) {
+    if (!hasJsDocs(node))
+        return {};
+    const bag = {};
+    for (const jsdoc of node.getJsDocs()) {
+        for (const tag of jsdoc.getTags()) {
+            const name = tag.getTagName();
+            const value = (tag.getCommentText() ?? '').split('\n')[0].trim();
+            (bag[name] ??= []).push(value);
+        }
+    }
+    return bag;
+}
+/**
+ * Resolve the `@Scope` tag values on a node into a flat set of scope names.
+ * Accepts comma-separated lists with optional whitespace
+ * (`@Scope internal,admin`, `@Scope internal, admin`) and multiple occurrences
+ * (`@Scope internal` on one line and `@Scope admin` on another).
+ */
+function getScopes(bag) {
+    return new Set((bag.Scope ?? []).flatMap((v) => v
+        .split(',')
+        .map((s) => s.trim())
+        .filter(Boolean)));
+}
+/**
+ * Decide whether an item is visible under the active scopes.
+ *
+ *  - Untagged items (`itemScopes` empty) are always visible.
+ *  - When no scope is active, only untagged items are visible.
+ *  - Otherwise, visible iff at least one of the item's scopes is active.
+ */
+function isVisible(itemScopes, activeScopes) {
+    if (itemScopes.size === 0)
+        return true;
+    if (activeScopes.size === 0)
+        return false;
+    for (const s of itemScopes)
+        if (activeScopes.has(s))
+            return true;
+    return false;
+}
+/**
+ * Normalize an `--scope a,b --scope c` style CLI input (or a `scopes` config
+ * array) into a flat string list — comma-split, trimmed, falsy filtered.
+ */
+function parseScopeList(raw) {
+    if (raw === undefined)
+        return [];
+    const items = Array.isArray(raw) ? raw : [raw];
+    return items.flatMap((s) => s
+        .split(',')
+        .map((p) => p.trim())
+        .filter(Boolean));
+}
+// Matches an element-style open or close tag: <name> or </name>. The name must
+// look like a scope identifier — letters/digits/underscore/hyphen, leading
+// letter. Whether a match is an actual scope fragment (vs. literal prose) is
+// decided downstream against the known-scope vocabulary.
+const FRAGMENT_TAG = /<\/?([A-Za-z][A-Za-z0-9_-]*)>/g;
+/**
+ * Filter `<scope>…</scope>` fragments inside a JSDoc description.
+ *
+ *  - Untagged text passes through unchanged.
+ *  - `<X>…</X>` keeps its inner text when `X ∈ activeScopes`; otherwise the
+ *    whole block (open tag → close tag) is removed.
+ *  - The remaining text is normalized: lines that contained only an open/close
+ *    tag are dropped (including their newline), runs of 3+ newlines collapse
+ *    to 2, and the result is trimmed.
+ *  - Nested fragments, mismatched close tags, and unclosed open tags throw.
+ *
+ * Only names that are *known scopes* are treated as fragment delimiters. Pass
+ * the project's scope vocabulary via `ctx.knownScopes`; any other angle-bracket
+ * token — generics in prose (`Array<string>`), placeholders (`<id>`, `<token>`),
+ * inline HTML (`<b>…</b>`) — passes through verbatim and never throws. When
+ * `ctx.knownScopes` is omitted, every `<name>` is treated as a fragment (legacy
+ * behavior, retained for direct callers and unit tests).
+ *
+ * The optional `ctx.itemPath` (e.g. `"User.email"`) is included in the error
+ * message so misconfigured comments are easy to locate.
+ */
+function filterScopedComments(text, activeScopes, ctx = {}) {
+    const where = ctx.itemPath ? ` at ${ctx.itemPath}` : '';
+    const known = ctx.knownScopes;
+    const isScopeTag = (name) => known === undefined || known.has(name);
+    let currentScope;
+    let keep = true;
+    let out = '';
+    let cursor = 0;
+    FRAGMENT_TAG.lastIndex = 0;
+    for (let m = FRAGMENT_TAG.exec(text); m !== null; m = FRAGMENT_TAG.exec(text)) {
+        const before = text.slice(cursor, m.index);
+        if (keep)
+            out += before;
+        cursor = m.index + m[0].length;
+        const name = m[1];
+        const isClose = m[0].startsWith('</');
+        // Not a scope name — ordinary prose. Emit it verbatim (when we're keeping
+        // the surrounding text) and leave the fragment state untouched.
+        if (!isScopeTag(name)) {
+            if (keep)
+                out += m[0];
+            continue;
+        }
+        if (!isClose) {
+            if (currentScope !== undefined) {
+                throw new Error(`Nested scope fragments are not allowed${where}: <${name}> inside <${currentScope}>.`);
+            }
+            currentScope = name;
+            keep = activeScopes.has(name);
+        }
+        else {
+            if (currentScope === undefined) {
+                throw new Error(`Unmatched closing scope tag </${name}>${where}.`);
+            }
+            if (currentScope !== name) {
+                throw new Error(`Mismatched scope tag </${name}>${where} (expected </${currentScope}>).`);
+            }
+            currentScope = undefined;
+            keep = true;
+        }
+    }
+    if (currentScope !== undefined) {
+        throw new Error(`Unclosed scope fragment <${currentScope}>${where}.`);
+    }
+    if (keep)
+        out += text.slice(cursor);
+    return normalizeFiltered(out);
+}
+function normalizeFiltered(text) {
+    // Drop lines whose remaining content is only whitespace AND that came from a
+    // removed tag — heuristic: any line that, after trim, is empty stays as a
+    // blank line, but we then collapse runs.
+    const noBlankLineRuns = text
+        .split('\n')
+        .map((line) => (line.trim() === '' ? '' : line))
+        .join('\n')
+        .replace(/\n{3,}/g, '\n\n');
+    return noBlankLineRuns.trim();
+}
+//# sourceMappingURL=tags.js.map

package/dist/parser/tags.js.map

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

package/dist/types/openapi.d.ts

@@ -0,0 +1,42 @@
+export type OpenApiSchema = Record<string, unknown>;
+export interface OpenApiServer {
+    url: string;
+    description?: string;
+    variables?: Record<string, {
+        default: string;
+        enum?: string[];
+        description?: string;
+    }>;
+}
+export interface OpenApiInfo {
+    title: string;
+    version: string;
+    description?: string;
+    termsOfService?: string;
+    contact?: {
+        name?: string;
+        url?: string;
+        email?: string;
+    };
+    license?: {
+        name: string;
+        url?: string;
+    };
+}
+export type OpenApiSecurityScheme = Record<string, unknown>;
+export type OpenApiSecurityRequirement = Record<string, string[]>;
+export interface OpenApiDocument {
+    openapi: string;
+    info: OpenApiInfo;
+    servers?: OpenApiServer[];
+    paths: Record<string, Record<string, unknown>>;
+    components?: {
+        schemas?: Record<string, OpenApiSchema>;
+        securitySchemes?: Record<string, OpenApiSecurityScheme>;
+    };
+    security?: OpenApiSecurityRequirement[];
+    tags?: {
+        name: string;
+        description?: string;
+    }[];
+}

package/dist/types/openapi.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=openapi.js.map

package/dist/types/openapi.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"openapi.js","sourceRoot":"","sources":["../../src/types/openapi.ts"],"names":[],"mappings":""}