@e22m4u/js-openapi 0.0.5 → 0.0.7

package/src/oa-document-builder.js

@@ -1,8 +1,8 @@
-import {OADocumentScope} from './oa-document-scope.js';
 import {InvalidArgumentError} from '@e22m4u/js-format';
-import {normalizePath} from './utils/normalize-path.js';
+import {OAOperationGroup} from './oa-operation-group.js';
 import {isServiceContainer, Service} from '@e22m4u/js-service';
-import {validateShallowOADocument} from './oa-document-object/index.js';
+import {validateOADocumentObject} from './oa-document-object/index.js';
+import {escapeJsonPointer} from './json-pointer/escape-json-pointer.js';
 import {OPENAPI_VERSION, OAOperationMethod} from './oa-specification.js';
 
 /**
@@ -26,6 +26,11 @@ export const OAComponentType = {
  */
 export const OA_COMPONENT_TYPES = Object.values(OAComponentType);
 
+/**
+ * Component name RegExp.
+ */
+export const OA_COMPONENT_NAME_REGEX = /^[a-zA-Z0-9.\-_]+$/;
+
 /**
  * Component type to components key map.
  */
@@ -42,6 +47,23 @@ export const OA_COMPONENT_TYPE_TO_COMPONENTS_KEY_MAP = {
   [OAComponentType.PATH_ITEM]: 'pathItems',
 };
 
+/**
+ * Component type to definition name map.
+ * "#/$defs/${name}"
+ */
+export const OA_COMPONENT_TYPE_TO_DEFINITION_NAME_MAP = {
+  [OAComponentType.SCHEMA]: 'schema',
+  [OAComponentType.RESPONSE]: 'response-or-reference',
+  [OAComponentType.PARAMETER]: 'parameter-or-reference',
+  [OAComponentType.EXAMPLE]: 'example-or-reference',
+  [OAComponentType.REQUEST_BODY]: 'request-body-or-reference',
+  [OAComponentType.HEADER]: 'header-or-reference',
+  [OAComponentType.SECURITY_SCHEME]: 'security-scheme-or-reference',
+  [OAComponentType.LINK]: 'link-or-reference',
+  [OAComponentType.CALLBACK]: 'callbacks-or-reference',
+  [OAComponentType.PATH_ITEM]: 'path-item',
+};
+
 /**
  * OpenAPI Document builder.
  */
@@ -58,84 +80,73 @@ export class OADocumentBuilder extends Service {
       title: 'API Documentation',
       version: '0.0.1',
     },
+    paths: {},
   };
 
   /**
    * Constructor.
    *
-   * @param {object} [containerOrDocument]
-   * @param {object} [document]
+   * @param {import('@e22m4u/js-service').ServiceContainer|import('./oa-document-builder.js').OADocumentInput} containerOrDocument
+   * @param {import('./oa-document-builder.js').OADocumentInput} document
    */
   constructor(containerOrDocument, document) {
     if (isServiceContainer(containerOrDocument)) {
       super(containerOrDocument);
     } else {
       super();
-      document = containerOrDocument;
+      // containerOrDocument
+      if (containerOrDocument !== undefined) {
+        if (
+          !containerOrDocument ||
+          typeof containerOrDocument !== 'object' ||
+          Array.isArray(containerOrDocument)
+        ) {
+          throw new InvalidArgumentError(
+            'Parameter "containerOrDocument" must be an Object, ' +
+              'but %v was given.',
+            containerOrDocument,
+          );
+        }
+      }
+      document = document === undefined ? containerOrDocument : document;
     }
+    // document
     if (document !== undefined) {
-      // если схема документа не является
-      // объектом, то выбрасывается ошибка
       if (
         !document ||
         typeof document !== 'object' ||
         Array.isArray(document)
       ) {
         throw new InvalidArgumentError(
-          'OpenAPI Document Object must be an Object, but %v was given.',
+          'Parameter "document" must be an Object, but %v was given.',
           document,
         );
       }
-      // чтобы избежать мутации аргумента,
-      // выполняется копирование документа
       document = structuredClone(document);
-      // если версия OpenAPI не определена,
-      // то устанавливается версия по умолчанию
-      if (!document.openapi) {
-        document.openapi = this._document.openapi;
-      }
-      // если Info Object не определен,
-      // то устанавливается значение по умолчанию
-      if (!document.info) {
-        document.info = this._document.info;
-      }
-      // если свойство "info" не является
-      // объектом, то выбрасывается ошибка
-      if (
-        !document.info ||
-        typeof document.info !== 'object' ||
-        Array.isArray(document.info)
-      ) {
-        throw new InvalidArgumentError(
-          'Property "info" must be an Object, but %v was given.',
-          document.info,
-        );
-      }
-      // если свойство "info.title" не определено,
-      // то устанавливается значение по умолчанию
-      if (!document.info.title) {
-        document.info.title = this._document.info.title;
-      }
-      // если свойство "info.version" не определено,
-      // то устанавливается значение по умолчанию
-      if (!document.info.version) {
-        document.info.version = this._document.info.version;
-      }
-      // поверхностная проверка свойств документа
-      // выполняется после установки значений по умолчанию
-      validateShallowOADocument(document);
-      this._document = document;
+      this._document = {...this._document, ...document};
     }
+    // validate
+    validateOADocumentObject(this._document);
+  }
+
+  /**
+   * Get document object reference.
+   *
+   * @returns {import('./oa-specification.js').OADocumentObject}
+   */
+  getDocumentObjectRef() {
+    return this._document;
   }
 
   /**
    * Define component.
    *
    * @param {string} type
-   * @param {object} definition
+   * @param {object} name
+   * @param {object} component
    * @returns {this}
    */
-  defineComponent(type, definition) {
+  defineComponent(type, name, component) {
     // type
     if (!OA_COMPONENT_TYPES.includes(type)) {
       throw new InvalidArgumentError(
@@ -143,49 +154,56 @@ export class OADocumentBuilder extends Service {
         type,
       );
     }
-    // definition
-    if (
-      !definition ||
-      typeof definition !== 'object' ||
-      Array.isArray(definition)
-    ) {
+    // name
+    if (!name || typeof name !== 'string') {
       throw new InvalidArgumentError(
-        'Component definition must be an Object, but %v was given.',
-        definition,
+        'Component name must be a non-empty String, but %v was given.',
+        name,
       );
     }
-    // definition.name
-    if (!definition.name || typeof definition.name !== 'string') {
+    if (!OA_COMPONENT_NAME_REGEX.test(name)) {
       throw new InvalidArgumentError(
-        'Property "name" must be a non-empty String, but %v was given.',
-        definition.name,
+        'Component name %v contains invalid characters.',
+        name,
       );
     }
-    // definition[type]
-    const component = definition[type];
+    // component
     if (
       !component ||
       typeof component !== 'object' ||
       Array.isArray(component)
     ) {
       throw new InvalidArgumentError(
-        'Property %v must be an Object, but %v was given.',
-        type,
+        'Component %v must be an Object, but %v was given.',
+        name,
         component,
       );
     }
     // components key
-    const key = OA_COMPONENT_TYPE_TO_COMPONENTS_KEY_MAP[type];
-    if (!key) {
+    const componentsKey = OA_COMPONENT_TYPE_TO_COMPONENTS_KEY_MAP[type];
+    if (!componentsKey) {
       throw new InvalidArgumentError(
         'Component type %v does not have a reference to the components key.',
-        type,
+        componentsKey,
       );
     }
+    // definition name
+    const definitionName = OA_COMPONENT_TYPE_TO_DEFINITION_NAME_MAP[type];
+    if (!definitionName) {
+      throw new InvalidArgumentError(
+        'Component type %v does not have a reference to the definition name.',
+        definitionName,
+      );
+    }
+    // validation
+    validateOADocumentObject(component, {
+      schemaUri: `#/$defs/${definitionName}`,
+      dataSourceUri: `#/components/${componentsKey}/${escapeJsonPointer(name)}`,
+    });
     this._document.components = this._document.components || {};
-    this._document.components[key] = this._document.components[key] || {};
-    this._document.components[key][definition.name] =
-      structuredClone(component);
+    this._document.components[componentsKey] =
+      this._document.components[componentsKey] || {};
+    this._document.components[componentsKey][name] = structuredClone(component);
     return this;
   }
 
@@ -197,25 +215,38 @@ export class OADocumentBuilder extends Service {
    * @returns {boolean}
    */
   hasComponent(type, name) {
+    // type
+    if (!OA_COMPONENT_TYPES.includes(type)) {
+      throw new InvalidArgumentError(
+        'Components type %v is not supported.',
+        type,
+      );
+    }
     // name
     if (!name || typeof name !== 'string') {
       throw new InvalidArgumentError(
-        'Parameter "name" must be a non-empty String, but %v was given.',
+        'Component name must be a non-empty String, but %v was given.',
+        name,
+      );
+    }
+    if (!OA_COMPONENT_NAME_REGEX.test(name)) {
+      throw new InvalidArgumentError(
+        'Component name %v contains invalid characters.',
         name,
       );
     }
     // components key
-    const key = OA_COMPONENT_TYPE_TO_COMPONENTS_KEY_MAP[type];
-    if (!key) {
+    const componentsKey = OA_COMPONENT_TYPE_TO_COMPONENTS_KEY_MAP[type];
+    if (!componentsKey) {
       throw new InvalidArgumentError(
         'Component type %v does not have a reference to the components key.',
-        type,
+        componentsKey,
       );
     }
     return Boolean(
       this._document.components &&
-      this._document.components[key] &&
-      this._document.components[key][name],
+      this._document.components[componentsKey] &&
+      this._document.components[componentsKey][name],
     );
   }
 
@@ -227,16 +258,29 @@ export class OADocumentBuilder extends Service {
    * @returns {object}
    */
   getComponent(type, name) {
+    // type
+    if (!OA_COMPONENT_TYPES.includes(type)) {
+      throw new InvalidArgumentError(
+        'Components type %v is not supported.',
+        type,
+      );
+    }
     // name
     if (!name || typeof name !== 'string') {
       throw new InvalidArgumentError(
-        'Parameter "name" must be a non-empty String, but %v was given.',
+        'Component name must be a non-empty String, but %v was given.',
+        name,
+      );
+    }
+    if (!OA_COMPONENT_NAME_REGEX.test(name)) {
+      throw new InvalidArgumentError(
+        'Component name %v contains invalid characters.',
         name,
       );
     }
     // components key
-    const key = OA_COMPONENT_TYPE_TO_COMPONENTS_KEY_MAP[type];
-    if (!key) {
+    const componentsKey = OA_COMPONENT_TYPE_TO_COMPONENTS_KEY_MAP[type];
+    if (!componentsKey) {
       throw new InvalidArgumentError(
         'Component type %v does not have a reference to the components key.',
         type,
@@ -245,12 +289,12 @@ export class OADocumentBuilder extends Service {
     const component =
       this._document &&
       this._document.components &&
-      this._document.components[key] &&
-      this._document.components[key][name];
+      this._document.components[componentsKey] &&
+      this._document.components[componentsKey][name];
     if (!component) {
       throw new InvalidArgumentError(
         'Component "#/components/%s/%s" does not exist.',
-        key,
+        componentsKey,
         name,
       );
     }
@@ -260,110 +304,122 @@ export class OADocumentBuilder extends Service {
   /**
    * Define schema component.
    *
-   * @param {object} schemaDef
+   * @param {string} name
+   * @param {object} component
    * @returns {this}
    */
-  defineSchemaComponent(schemaDef) {
-    return this.defineComponent(OAComponentType.SCHEMA, schemaDef);
+  defineSchemaComponent(name, component) {
+    return this.defineComponent(OAComponentType.SCHEMA, name, component);
   }
 
   /**
    * Define response component.
    *
-   * @param {object} responseDef
+   * @param {string} name
+   * @param {object} component
    * @returns {this}
    */
-  defineResponseComponent(responseDef) {
-    return this.defineComponent(OAComponentType.RESPONSE, responseDef);
+  defineResponseComponent(name, component) {
+    return this.defineComponent(OAComponentType.RESPONSE, name, component);
   }
 
   /**
    * Define parameter component.
    *
-   * @param {object} parameterDef
+   * @param {string} name
+   * @param {object} component
    * @returns {this}
    */
-  defineParameterComponent(parameterDef) {
-    return this.defineComponent(OAComponentType.PARAMETER, parameterDef);
+  defineParameterComponent(name, component) {
+    return this.defineComponent(OAComponentType.PARAMETER, name, component);
   }
 
   /**
    * Define example component.
    *
-   * @param {object} exampleDef
+   * @param {string} name
+   * @param {object} component
    * @returns {this}
    */
-  defineExampleComponent(exampleDef) {
-    return this.defineComponent(OAComponentType.EXAMPLE, exampleDef);
+  defineExampleComponent(name, component) {
+    return this.defineComponent(OAComponentType.EXAMPLE, name, component);
   }
 
   /**
    * Define request body component.
    *
-   * @param {object} requestBodyDef
+   * @param {string} name
+   * @param {object} component
    * @returns {this}
    */
-  defineRequestBodyComponent(requestBodyDef) {
-    return this.defineComponent(OAComponentType.REQUEST_BODY, requestBodyDef);
+  defineRequestBodyComponent(name, component) {
+    return this.defineComponent(OAComponentType.REQUEST_BODY, name, component);
   }
 
   /**
    * Define header component.
    *
-   * @param {object} headerDef
+   * @param {string} name
+   * @param {object} component
    * @returns {this}
    */
-  defineHeaderComponent(headerDef) {
-    return this.defineComponent(OAComponentType.HEADER, headerDef);
+  defineHeaderComponent(name, component) {
+    return this.defineComponent(OAComponentType.HEADER, name, component);
   }
 
   /**
    * Define security scheme component.
    *
-   * @param {object} securitySchemeDef
+   * @param {string} name
+   * @param {object} component
    * @returns {this}
    */
-  defineSecuritySchemeComponent(securitySchemeDef) {
+  defineSecuritySchemeComponent(name, component) {
     return this.defineComponent(
       OAComponentType.SECURITY_SCHEME,
-      securitySchemeDef,
+      name,
+      component,
     );
   }
 
   /**
    * Define link component.
    *
-   * @param {object} linkDef
+   * @param {string} name
+   * @param {object} component
    * @returns {this}
    */
-  defineLinkComponent(linkDef) {
-    return this.defineComponent(OAComponentType.LINK, linkDef);
+  defineLinkComponent(name, component) {
+    return this.defineComponent(OAComponentType.LINK, name, component);
   }
 
   /**
    * Define callback component.
    *
-   * @param {object} callbackDef
+   * @param {string} name
+   * @param {object} component
    * @returns {this}
    */
-  defineCallbackComponent(callbackDef) {
-    return this.defineComponent(OAComponentType.CALLBACK, callbackDef);
+  defineCallbackComponent(name, component) {
+    return this.defineComponent(OAComponentType.CALLBACK, name, component);
   }
 
   /**
    * Define path item component.
    *
-   * @param {object} pathItemDef
+   * @param {string} name
+   * @param {object} component
    * @returns {this}
    */
-  definePathItemComponent(pathItemDef) {
-    return this.defineComponent(OAComponentType.PATH_ITEM, pathItemDef);
+  definePathItemComponent(name, component) {
+    return this.defineComponent(OAComponentType.PATH_ITEM, name, component);
   }
 
   /**
    * Define operation.
    *
-   * @param {object} operationDef
+   * @param {import('./oa-document-builder.js').OAOperationDefinition} operationDef
+   * @returns {this}
    */
   defineOperation(operationDef) {
     if (
@@ -377,56 +433,66 @@ export class OADocumentBuilder extends Service {
       );
     }
     // 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,
+        );
+      }
+      // validation
+      validateOADocumentObject(operationDef.operation, {
+        schemaUri: '#/$defs/operation',
+        dataSourceUri: `#/paths/${escapeJsonPointer(operationDef.path)}/${escapeJsonPointer(operationDef.method)}`,
+      });
     }
-    const normalizedPath = normalizePath(operationDef.path);
+    // создание поверхностной копии определения
+    // операции для избежания мутации аргумента
+    const operation = operationDef.operation
+      ? structuredClone(operationDef.operation)
+      : {};
     if (!this._document.paths) {
       this._document.paths = {};
     }
-    if (!this._document.paths[normalizedPath]) {
-      this._document.paths[normalizedPath] = {};
+    if (!this._document.paths[operationDef.path]) {
+      this._document.paths[operationDef.path] = {};
     }
-    this._document.paths[normalizedPath][operationDef.method] = structuredClone(
-      operationDef.operation,
-    );
+    this._document.paths[operationDef.path][operationDef.method] = operation;
+    return this;
   }
 
   /**
-   * Create scope.
+   * Create operation group.
    *
-   * @param {object} [options]
-   * @returns {OADocumentScope}
+   * @param {import('./oa-operation-group.js').OAOperationGroupOptions} [options]
+   * @returns {OAOperationGroup}
    */
-  createScope(options) {
-    return new OADocumentScope(this, options);
+  createOperationGroup(options) {
+    return new OAOperationGroup(this, options);
   }
 
   /**