@nldoc/openapi-utils

NLdoc OpenAPI Utilities

A TypeScript utility library for building OpenAPI 3.1.0 specifications programmatically. This library provides a fluent, type-safe API for creating and managing OpenAPI schemas, properties, and references.

Overview

This library provides a comprehensive set of utilities for working with OpenAPI specifications including:

• Type-safe property builders for OpenAPI schemas
• Resource and collection property management
• Schema component references and examples
• JSON type definitions and utilities
• Fluent API for building complex schemas

The utilities provide a consistent, type-safe way to construct OpenAPI specifications, enabling better API documentation, validation, and integration with OpenAPI-based tools.

Getting Started

Prerequisites

• Node.js >= 22.0.0 < 23.0.0
• npm >= 10.0.0 < 12.0.0

Installation

Install the package via npm:

npm install @nldoc/openapi-utils

Or using yarn:

yarn add @nldoc/openapi-utils

Basic Usage

import {
  Property,
  Resource,
  CollectionProperty,
  ComponentSchemaReference
} from '@nldoc/openapi-utils';

// Create a simple property
const nameProperty = new Property('string')
  .setTitle('Name')
  .setDescription('The name of the resource')
  .setMinLength(1)
  .setMaxLength(100);

// Create a resource with properties
const userResource = new Resource('User', 'object')
  .addProperty('id', new Property('string').setFormat('uuid'), true)
  .addProperty('name', nameProperty, true)
  .addProperty('email', new Property('string').setFormat('email'), true)
  .addExample({
    id: '123e4567-e89b-12d3-a456-426614174000',
    name: 'John Doe',
    email: '[e-mail]'
  });

// Create a collection property
const usersCollection = new CollectionProperty(['User'])
  .setMinItems(0)
  .setDescription('A collection of users');

// Create a schema reference
const userRef = ComponentSchemaReference('User');

Development

Local Setup

• Clone the repository:

  git clone https://gitlab.com/logius/nldoc/lib/typescript/openapi-utils.git
  cd openapi-utils
  

• Install dependencies:

  npm install
  

• Build the project:

  npm run build
  

Available Scripts

• npm run test - Run the test suite with Vitest and coverage
• npm run build - Build the TypeScript files for distribution
• npm run lint - Lint the codebase using ESLint
• npm run format - Format code using Prettier
• npm run format:check - Check code formatting
• npm run fix - Auto-fix linting and formatting issues
• npm run release - Create a semantic release

API Components

The library provides several key classes and utilities:

Core Classes

• Property: Base class for creating OpenAPI schema properties
• Resource: Extended property class for creating complex object schemas
• CollectionProperty: Specialized property for array/collection types

Reference Utilities

• ComponentSchemaReference: Create references to schema components
• ComponentExampleReference: Create references to example components
• ReferenceKey: Generate reference keys for components

Type Definitions

• Json: TypeScript types for JSON values
• StrictOpenAPIObject: Strict typing for OpenAPI objects
• OmitIndexSignature: Utility type for omitting index signatures

Helper Functions

• assertHasTitle: Assertion function for schema titles
• isArrayOfOneEmptyArray: Check for empty array patterns

API Documentation

Property Class

The Property class provides a fluent API for building OpenAPI schema properties:

const property = new Property('string')
  .setTitle('Example Property')
  .setDescription('A description of the property')
  .setFormat('email')
  .setMinLength(5)
  .setMaxLength(100)
  .addExample('[e-mail]')
  .setDefault('[e-mail]');

Resource Class

The Resource class extends Property for creating object schemas:

const resource = new Resource('Product', 'object')
  .addProperty('id', idProperty, true) // required
  .addProperty('name', nameProperty, true)
  .addProperty('price', priceProperty, false) // optional
  .setProperties({ description: descProperty }, ['description']);

CollectionProperty Class

The CollectionProperty class handles array types with discriminators:

const collection = new CollectionProperty(['Product', 'Service'], 'type')
  .setMinItems(1)
  .addExample([
    { type: 'Product', id: '1', name: 'Widget' },
    { type: 'Service', id: '2', name: 'Support' }
  ]);

Testing

Run the test suite:

npm test

Contributing

We welcome contributions! Please ensure:

• All tests pass (npm test)
• Code is properly formatted (npm run format:check)
• Linting rules are followed (npm run lint)
• Test coverage is maintained

License

This project is licensed under the European Union Public License 1.2 - see LICENSE for details.

Acknowledgements

• Built for OpenAPI 3.1.0 specification
• Uses openapi3-ts for TypeScript definitions
• Integrates with Zod for schema validation