@bernierllc/jsdoc-openapi-parser

JSDoc and TSDoc comment parsing utilities for generating OpenAPI operations.

Installation

npm install @bernierllc/jsdoc-openapi-parser

Usage

import { JSDocOpenAPIParser } from '@bernierllc/jsdoc-openapi-parser';

const parser = new JSDocOpenAPIParser({ inferTypes: true });

const result = parser.parseComment(`
/**
 * Create a user
 * @summary Create user
 * @param {CreateUserRequest} input.body.required - Request payload
 * @returns {User} 201 - Created
 */
`);

console.log(result.openapi.summary); // "Create user"

API Reference

JSDocOpenAPIParser

| Method | Description | | --- | --- | | parseComment(comment, context?) | Parse a single block comment into a structured result with OpenAPI metadata. | | parseSource(source, filePath?) | Extract and parse all documentation comments from a source string. | | parseFile(filePath) | Read a file and parse all documentation comments. | | commentToOperation(comment) | Convert a comment to an OpenAPI OperationObject. | | tagsToParameters(tags) | Transform supported tags into OpenAPI parameter definitions. | | tagsToResponses(tags) | Build response objects from @returns, @throws, and @response tags. | | tagsToSchemas(tags) | Build schema definitions for inline YAML blocks or documented types. |

Configuration Options

| Option | Type | Description | | --- | --- | --- | | customTags | string[] | Register additional tags to preserve in the parsed output. | | strictMode | boolean | Enable stricter validation and normalized output. | | preserveComments | boolean | Include original comment text in the parsed result. | | inferTypes | boolean | Enable TypeScript-aware type inference for undocumented fields. | | schemaBuilder | OpenAPISchemaBuilder | Optional schema builder instance from @bernierllc/openapi-schema-builder. | | fileResolver | FileResolver | Optional file loader override. Defaults to @bernierllc/file-handler. |

Configuration

The parser can be configured with optional collaborators:

• Schema Builder: Inject an instance from @bernierllc/openapi-schema-builder to normalise schemas.
• File Resolver: Provide a custom loader implementing read(filePath) for virtual filesystems.
• YAML Parsing: YAML blocks are parsed with a lightweight built-in parser and validated before use.

Integration Status

• Logger: not-applicable – the package is a deterministic parser with no side effects.
• Docs-Suite: ready – README and generated TypeScript types can be consumed directly.
• NeverHub: not-applicable – core utility without networking concerns.

Examples

See the examples/ directory for runnable parsing samples, including YAML-driven operations and inline schema definitions.

Security

• All external YAML content is validated before inclusion.
• Only documented tags are transformed into OpenAPI output.
• Strict TypeScript compiler settings prevent unsafe code paths.

License

Copyright (c) Bernier LLC. Provided for internal use only.