@e22m4u/js-openapi 0.0.5 → 0.0.7

package/src/oa-document-object/index.d.ts

@@ -1 +1 @@
-export * from './validate-shallow-oa-document.js';
+export * from './validate-oa-document-object.js';

package/src/oa-document-object/index.js

@@ -1 +1 @@
-export * from './validate-shallow-oa-document.js';
+export * from './validate-oa-document-object.js';

package/src/oa-document-object/validate-oa-document-object.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Document object validation options.
+ */
+export type OADocumentObjectValidationOptions = {
+  schemaUri?: string;
+  dataSourceUri?: string;
+};
+
+/**
+ * Validate OADocumentObject.
+ *
+ * @param data
+ * @param options
+ */
+export function validateOADocumentObject(
+  data: any,
+  options?: OADocumentObjectValidationOptions,
+): void;

package/src/oa-document-object/validate-oa-document-object.js

@@ -0,0 +1,53 @@
+import {InvalidArgumentError} from '@e22m4u/js-format';
+import {ajv, OA_DOCUMENT_OBJECT_JSON_SCHEMA_URI} from '../ajv.js';
+import {OADocumentObjectValidationError} from '../errors/index.js';
+
+/**
+ * Validate OADocumentObject.
+ *
+ * @param {*} data
+ * @param {*} options
+ */
+export function validateOADocumentObject(data, options = {}) {
+  if (!options || typeof options !== 'object' || Array.isArray(options)) {
+    throw new InvalidArgumentError(
+      'Parameter "options" must be an Object, but %v was given.',
+      options,
+    );
+  }
+  if (options.schemaUri !== undefined) {
+    if (typeof options.schemaUri !== 'string') {
+      throw new InvalidArgumentError(
+        'Option "schemaUri" must be a String, but %v was given.',
+        options.schemaUri,
+      );
+    }
+  }
+  if (options.dataSourceUri !== undefined) {
+    if (typeof options.dataSourceUri !== 'string') {
+      throw new InvalidArgumentError(
+        'Option "dataSourceUri" must be a String, but %v was given.',
+        options.dataSourceUri,
+      );
+    }
+  }
+  const validate = ajv.getSchema(
+    `${OA_DOCUMENT_OBJECT_JSON_SCHEMA_URI}${options.schemaUri || ''}`,
+  );
+  const isValid = validate(data);
+  if (!isValid) {
+    const error = validate.errors[0];
+    let instancePath = error.instancePath || '';
+    let dataSourceUri = options.dataSourceUri || '';
+    if (!options.schemaUri && !options.dataSourceUri) {
+      dataSourceUri = '#';
+    }
+    throw new OADocumentObjectValidationError(
+      'Value at %v %s.',
+      dataSourceUri && error.instancePath
+        ? [dataSourceUri, error.instancePath].join('/').replace(/\/+/g, '/')
+        : dataSourceUri + instancePath,
+      error.message.replace(/'/g, '"'),
+    );
+  }
+}

package/src/oa-document-object/validate-oa-document-object.spec.js

@@ -0,0 +1,122 @@
+import {expect} from 'chai';
+import {validateOADocumentObject} from './validate-oa-document-object.js';
+import {format} from '@e22m4u/js-format';
+
+const VALID_DOC_SAMPLE = {
+  openapi: '3.1.2',
+  info: {
+    title: 'API Documentation',
+    version: '0.0.1',
+  },
+  components: {},
+};
+
+describe('validateOADocumentObject', function () {
+  it('should require the parameter "option" to be an Object', function () {
+    const throwable = v => () => validateOADocumentObject(VALID_DOC_SAMPLE, v);
+    const error = s =>
+      format('Parameter "options" must be an Object, but %s was given.', s);
+    expect(throwable('str')).to.throw(error('"str"'));
+    expect(throwable('')).to.throw(error('""'));
+    expect(throwable(10)).to.throw(error('10'));
+    expect(throwable(0)).to.throw(error('0'));
+    expect(throwable(true)).to.throw(error('true'));
+    expect(throwable(false)).to.throw(error('false'));
+    expect(throwable([])).to.throw(error('Array'));
+    expect(throwable(null)).to.throw(error('null'));
+    throwable({})();
+    throwable(undefined)();
+  });
+
+  it('should require the option "schemaUri" to be a String', function () {
+    const throwable = v => () =>
+      validateOADocumentObject(VALID_DOC_SAMPLE, {schemaUri: v});
+    const error = s =>
+      format('Option "schemaUri" must be a String, but %s was given.', s);
+    expect(throwable(10)).to.throw(error('10'));
+    expect(throwable(0)).to.throw(error('0'));
+    expect(throwable(true)).to.throw(error('true'));
+    expect(throwable(false)).to.throw(error('false'));
+    expect(throwable([])).to.throw(error('Array'));
+    expect(throwable({})).to.throw(error('Object'));
+    expect(throwable(null)).to.throw(error('null'));
+    throwable('#')();
+    throwable(undefined)();
+  });
+
+  it('should require the option "dataSourceUri" to be a String', function () {
+    const throwable = v => () =>
+      validateOADocumentObject(VALID_DOC_SAMPLE, {dataSourceUri: v});
+    const error = s =>
+      format('Option "dataSourceUri" must be a String, but %s was given.', s);
+    expect(throwable(10)).to.throw(error('10'));
+    expect(throwable(0)).to.throw(error('0'));
+    expect(throwable(true)).to.throw(error('true'));
+    expect(throwable(false)).to.throw(error('false'));
+    expect(throwable([])).to.throw(error('Array'));
+    expect(throwable({})).to.throw(error('Object'));
+    expect(throwable(null)).to.throw(error('null'));
+    throwable('/str')();
+    throwable('')();
+    throwable(undefined)();
+  });
+
+  it('should pass validation for a valid document', function () {
+    validateOADocumentObject({
+      openapi: '3.1.2',
+      info: {
+        title: 'API Documentation',
+        version: '0.0.1',
+      },
+      components: {},
+    });
+  });
+
+  it('should require the "openapi" keyword', function () {
+    const throwable = () =>
+      validateOADocumentObject({
+        info: {
+          title: 'API Documentation',
+          version: '0.0.1',
+        },
+        components: {},
+      });
+    expect(throwable).to.throw(
+      'Value at "#" must have required property "openapi".',
+    );
+  });
+
+  it('should require the "info" keyword', function () {
+    const throwable = () =>
+      validateOADocumentObject({
+        openapi: '3.1.2',
+        components: {},
+      });
+    expect(throwable).to.throw(
+      'Value at "#" must have required property "info".',
+    );
+  });
+
+  it('should allow to select the schema by the "schemaUri" option', function () {
+    const throwable = () =>
+      validateOADocumentObject({type: 123}, {schemaUri: '#/$defs/schema'});
+    expect(throwable).to.throw(
+      'Value at "/type" must be equal to one of the allowed values.',
+    );
+  });
+
+  it('should add the "dataSourceUri" option as prefix to the instance path', function () {
+    const throwable = () =>
+      validateOADocumentObject(
+        {type: 123},
+        {
+          schemaUri: '#/$defs/schema',
+          dataSourceUri: '#/components/schemas/mySchema',
+        },
+      );
+    expect(throwable).to.throw(
+      'Value at "#/components/schemas/mySchema/type" ' +
+        'must be equal to one of the allowed values.',
+    );
+  });
+});

package/src/{oa-document-scope.d.ts → oa-operation-group.d.ts}

@@ -4,22 +4,22 @@ import {
 } from './oa-document-builder.js';
 
 /**
- * Document scope options.
+ * Operation group options.
  */
-export type OADocumentScopeOptions = {
+export type OAOperationGroupOptions = {
   pathPrefix?: string;
   tags?: string[];
 };
 
 /**
- * Document scope.
+ * Operation group.
  */
-export declare class OADocumentScope {
+export declare class OAOperationGroup {
   /**
    * @param builder
    * @param options
    */
-  constructor(builder: OADocumentBuilder, options?: OADocumentScopeOptions);
+  constructor(builder: OADocumentBuilder, options?: OAOperationGroupOptions);
 
   /**
    * Get builder.
@@ -44,9 +44,9 @@ export declare class OADocumentScope {
   defineOperation(operationDef: OAOperationDefinition): this;
 
   /**
-   * Create scope.
+   * Create operation group.
    *
    * @param options
    */
-  createScope(options?: OADocumentScopeOptions): OADocumentScope;
+  createOperationGroup(options?: OAOperationGroupOptions): OAOperationGroup;
 }

package/src/{oa-document-scope.js → oa-operation-group.js}

@@ -1,12 +1,39 @@
 import {InvalidArgumentError} from '@e22m4u/js-format';
 import {OAOperationMethod} from './oa-specification.js';
-import {joinPath, normalizePath} from './utils/index.js';
 import {OADocumentBuilder} from './oa-document-builder.js';
 
 /**
- * Document scope.
+ * Operation group.
+ *
+ * Предоставляет группу операций API с общими параметрами.
+ *
+ * - Общий префикс пути для всех операций в области.
+ * - Общие теги, применяемые ко всем операциям.
+ * - Возможность создания вложенных групп для иерархической организации.
+ *
+ * Пример:
+ * ```js
+ * // создание группы
+ * const usersOps = builder.createOperationGroup({
+ *   pathPrefix: '/users',
+ *   tags: ['Users']
+ * });
+ *
+ * // GET "/users/{id}"
+ * usersOps.defineOperation({
+ *   path: '/{id}',
+ *   method: OAOperationMethod.GET,
+ *   operation: { ... }
+ * });
+ *
+ * // вложенная группа "/users/admin"
+ * const adminOps = usersOps.createOperationGroup({
+ *   pathPrefix: '/admin',
+ *   tags: ['Admin']
+ * });
+ * ```
  */
-export class OADocumentScope {
+export class OAOperationGroup {
   /**
    * Builder.
    *
@@ -50,10 +77,15 @@ export class OADocumentScope {
     }
     // options.pathPrefix
     if (options.pathPrefix !== undefined) {
-      if (!options.pathPrefix || typeof options.pathPrefix !== 'string') {
+      if (typeof options.pathPrefix !== 'string') {
         throw new InvalidArgumentError(
-          'Property "pathPrefix" must be a non-empty String, ' +
-            'but %v was given.',
+          'Option "pathPrefix" must be a String, but %v was given.',
+          options.pathPrefix,
+        );
+      }
+      if (!options.pathPrefix.startsWith('/')) {
+        throw new InvalidArgumentError(
+          'Option "pathPrefix" must start with "/", but %v was given.',
           options.pathPrefix,
         );
       }
@@ -62,14 +94,15 @@ export class OADocumentScope {
     if (options.tags !== undefined) {
       if (!Array.isArray(options.tags)) {
         throw new InvalidArgumentError(
-          'Property "tags" must be an Array, but %v was given.',
+          'Option "tags" must be an Array, but %v was given.',
           options.tags,
         );
       }
       options.tags.forEach((tag, index) => {
         if (!tag || typeof tag !== 'string') {
           throw new InvalidArgumentError(
-            'Element "tags[%d]" must be a non-empty String, but %v was given.',
+            'Element %v in the option "tags" must be a non-empty String, ' +
+              'but %v was given.',
             index,
             tag,
           );
@@ -77,8 +110,8 @@ export class OADocumentScope {
       });
     }
     this._builder = builder;
-    this._pathPrefix = normalizePath(options.pathPrefix || '/');
-    this._tags = options.tags || [];
+    this._pathPrefix = options.pathPrefix || '/';
+    this._tags = [...new Set(options.tags || [])];
   }
 
   /**
@@ -111,7 +144,7 @@ export class OADocumentScope {
   /**
    * Define operation.
    *
-   * @param {object} operationDef
+   * @param {import('./oa-document-builder.js').OAOperationDefinition} operationDef
    * @returns {this}
    */
   defineOperation(operationDef) {
@@ -126,44 +159,53 @@ export class OADocumentScope {
       );
     }
     // path
-    if (!operationDef.path || typeof operationDef.path !== 'string') {
+    if (typeof operationDef.path !== 'string') {
       throw new InvalidArgumentError(
-        'Property "path" must be a non-empty String, but %v was given.',
+        'Keyword "path" must be a String, but %v was given.',
         operationDef.path,
       );
     }
-    // method
-    if (!operationDef.method || typeof operationDef.method !== 'string') {
+    if (!operationDef.path.startsWith('/')) {
       throw new InvalidArgumentError(
-        'Property "method" must be a non-empty String, but %v was given.',
-        operationDef.method,
+        'Keyword "path" must start with "/", but %v was given.',
+        operationDef.path,
       );
     }
+    // method
     if (!Object.values(OAOperationMethod).includes(operationDef.method)) {
       throw new InvalidArgumentError(
-        'Property "method" must be one of values: %l, but %v was given.',
-        Object.values(OAOperationMethod),
+        'Keyword "method" must be one of the allowed values, but %v was given.',
+        operationDef.method,
       );
     }
     // operation
-    if (
-      !operationDef.operation ||
-      typeof operationDef.operation !== 'object' ||
-      Array.isArray(operationDef.operation)
-    ) {
-      throw new InvalidArgumentError(
-        'Property "operation" must be an Object, but %v was given.',
-        operationDef.operation,
-      );
+    if (operationDef.operation !== undefined) {
+      if (
+        !operationDef.operation ||
+        typeof operationDef.operation !== 'object' ||
+        Array.isArray(operationDef.operation)
+      ) {
+        throw new InvalidArgumentError(
+          'Keyword "operation" must be an Object, but %v was given.',
+          operationDef.operation,
+        );
+      }
+    }
+    // объединение префикса и пути операции выполняется
+    // с учетом наличия косой черты в начале пути
+    let fullPath = this._pathPrefix;
+    if (operationDef.path !== '/') {
+      if (fullPath === '/') {
+        fullPath = operationDef.path;
+      } else {
+        fullPath += operationDef.path;
+      }
     }
-    // склеивание пути
-    const fullPath = joinPath(this._pathPrefix, operationDef.path);
-    // создание копии схемы операции
-    // чтобы избежать мутацию аргумента
-    const operation = structuredClone(operationDef.operation);
-    // объединение тегов текущей области
-    // с тегами текущей операции и удаление
-    // дубликатов
+    // создание поверхностной копии определения
+    // операции для избежания мутации аргумента
+    const operation = {...operationDef.operation};
+    // объединение тегов текущей области с тегами
+    // текущей операции и удаление дубликатов
     if (this._tags.length > 0) {
       operation.tags = [...this._tags, ...(operation.tags || [])];
       operation.tags = [...new Set(operation.tags)];
@@ -179,12 +221,12 @@ export class OADocumentScope {
   }
 
   /**
-   * Create scope.
+   * Create operation group.
    *
    * @param {object} [options]
-   * @returns {OADocumentScope}
+   * @returns {OAOperationGroup}
    */
-  createScope(options = {}) {
+  createOperationGroup(options = {}) {
     // options
     if (!options || typeof options !== 'object' || Array.isArray(options)) {
       throw new InvalidArgumentError(
@@ -194,10 +236,15 @@ export class OADocumentScope {
     }
     // options.pathPrefix
     if (options.pathPrefix !== undefined) {
-      if (!options.pathPrefix || typeof options.pathPrefix !== 'string') {
+      if (typeof options.pathPrefix !== 'string') {
         throw new InvalidArgumentError(
-          'Property "pathPrefix" must be a non-empty String, ' +
-            'but %v was given.',
+          'Option "pathPrefix" must be a String, but %v was given.',
+          options.pathPrefix,
+        );
+      }
+      if (!options.pathPrefix.startsWith('/')) {
+        throw new InvalidArgumentError(
+          'Option "pathPrefix" must start with "/", but %v was given.',
           options.pathPrefix,
         );
       }
@@ -206,22 +253,30 @@ export class OADocumentScope {
     if (options.tags !== undefined) {
       if (!Array.isArray(options.tags)) {
         throw new InvalidArgumentError(
-          'Property "tags" must be an Array, but %v was given.',
+          'Option "tags" must be an Array, but %v was given.',
           options.tags,
         );
       }
       options.tags.forEach((tag, index) => {
         if (!tag || typeof tag !== 'string') {
           throw new InvalidArgumentError(
-            'Element "tags[%d]" must be a non-empty String, but %v was given.',
+            'Element %v in the option "tags" must be a non-empty String, but %v was given.',
             index,
             tag,
           );
         }
       });
     }
-    return new OADocumentScope(this._builder, {
-      pathPrefix: joinPath(this._pathPrefix, options.pathPrefix),
+    let fullPathPrefix = this._pathPrefix;
+    if (options.pathPrefix && options.pathPrefix !== '/') {
+      if (fullPathPrefix === '/') {
+        fullPathPrefix = options.pathPrefix;
+      } else {
+        fullPathPrefix += options.pathPrefix;
+      }
+    }
+    return new OAOperationGroup(this._builder, {
+      pathPrefix: fullPathPrefix,
       tags: [...this._tags, ...(options.tags || [])],
     });
   }