@nldoc/openapi-utils - npm Package Compare versions

Comparing version 1.3.106 to 1.3.107

package.json

 {
     "name": "@nldoc/openapi-utils",
-    "version": "1.3.106",
+    "version": "1.3.107",
     "description": "Utilities for building OpenAPI specifications.",
@@ -19,3 +19,3 @@ "license": "EUPL-1.2",
     "scripts": {
-        "test": "npm run build && vitest run",
+        "test": "npm run build && npx vitest run --coverage",
         "format": "prettier . --write",
@@ -36,5 +36,5 @@ "format:check": "prettier . --check",
         "@vitest/coverage-v8": "^3.0.0",
-        "typescript": "^5.5.3",
+        "typescript": "^5.9.2",
         "vitest": "^3.0.0"
     }
 }

README.md

@@ -1,5 +0,202 @@
-## OpenAPI Utilities
+# NLdoc OpenAPI Utilities
 
-To install:
+[![pipeline status](https://gitlab.com/logius/nldoc/lib/typescript/openapi-utils/badges/main/pipeline.svg)](https://gitlab.com/logius/nldoc/lib/typescript/openapi-utils/-/commits/main)
+[![coverage report](https://gitlab.com/logius/nldoc/lib/typescript/openapi-utils/badges/main/coverage.svg?job=test)](https://gitlab.com/logius/nldoc/lib/typescript/openapi-utils/-/commits/main)
+[![Latest Release](https://gitlab.com/logius/nldoc/lib/typescript/openapi-utils/-/badges/release.svg)](https://gitlab.com/logius/nldoc/lib/typescript/openapi-utils/-/releases)
+[![NPM Version](https://img.shields.io/npm/v/@nldoc/openapi-utils)](https://www.npmjs.com/package/@nldoc/openapi-utils)
 
-`npm install @nldoc/openapi-utils`
+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:
+
+```bash
+npm install @nldoc/openapi-utils
+```
+
+Or using yarn:
+
+```bash
+yarn add @nldoc/openapi-utils
+```
+
+### Basic Usage
+
+```typescript
+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
+
+1. Clone the repository:
+
+   ```bash
+   git clone https://gitlab.com/logius/nldoc/lib/typescript/openapi-utils.git
+   cd openapi-utils
+   ```
+
+2. Install dependencies:
+
+   ```bash
+   npm install
+   ```
+
+3. Build the project:
+
+   ```bash
+   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:
+
+```typescript
+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:
+
+```typescript
+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:
+
+```typescript
+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:
+
+```bash
+npm test
+```
+
+## Contributing
+
+We welcome contributions! Please ensure:
+
+1. All tests pass (`npm test`)
+2. Code is properly formatted (`npm run format:check`)
+3. Linting rules are followed (`npm run lint`)
+4. Test coverage is maintained
+
+## License
+
+This project is licensed under the European Union Public License 1.2 - see [LICENSE](LICENSE) for details.
+
+## Acknowledgements
+
+- Built for [OpenAPI 3.1.0](https://spec.openapis.org/oas/v3.1.0) specification
+- Uses [openapi3-ts](https://www.npmjs.com/package/openapi3-ts) for TypeScript definitions
+- Integrates with [Zod](https://github.com/colinhacks/zod) for schema validation

No alert changes

Improved metrics

Total package byte prevSize

39671

17.61%

Number of lines in readme file

203

3283.33%

No dependency changes