README.md

@@ -67,12 +67,15 @@ builder.defineOperation({
 });
 ```
 
-Сборка документа.
+Формирование JSON документа.
 
 ```js
-const document = builder.build();
+const jsonDoc = builder.buildJson(2);
+// первый аргумент указывает количество пробелов
+// для каждого уровня вложенности, и может быть
+// опущен в целях экономии размера документа
 
-console.log(JSON.stringify(document, null, 2));
+console.log(jsonDoc);
 // {
 //   "openapi": "3.1.0",
 //   "info": {
@@ -123,7 +126,7 @@ builder.defineSchemaComponent({
 Регистрация компонента параметра.
 
 ```js
-import {OADataType, OAOperationMethod} from '@e22m4u/js-openapi';
+import {OADataType, OAParameterLocation} from '@e22m4u/js-openapi';
 
 builder.defineParameterComponent({
   name: 'idParam', // <= имя нового компонента

build-cjs.js

@@ -6,7 +6,7 @@ await esbuild.build({
   outfile: 'dist/cjs/index.cjs',
   format: 'cjs',
   platform: 'node',
-  target: ['node12'],
+  target: ['node18'],
   bundle: true,
   keepNames: true,
   external: [

dist/cjs/index.cjs

@@ -22,7 +22,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var index_exports = {};
 __export(index_exports, {
   OAApiKeyLocation: () => OAApiKeyLocation,
-  OAComponentType: () => OAComponentType,
+  OAComponentsSegment: () => OAComponentsSegment,
   OADataFormat: () => OADataFormat,
   OADataType: () => OADataType,
   OADocumentBuilder: () => OADocumentBuilder,
@@ -32,7 +32,6 @@ __export(index_exports, {
   OAParameterLocation: () => OAParameterLocation,
   OAParameterStyle: () => OAParameterStyle,
   OASecuritySchemeType: () => OASecuritySchemeType,
-  OA_COMPONENT_TYPE_TO_KEY_MAP: () => OA_COMPONENT_TYPE_TO_KEY_MAP,
   OPENAPI_VERSION: () => OPENAPI_VERSION,
   oaCallbackRef: () => oaCallbackRef,
   oaExampleRef: () => oaExampleRef,
@@ -49,66 +48,51 @@ module.exports = __toCommonJS(index_exports);
 
 // src/constants.js
 var OPENAPI_VERSION = "3.1.0";
+var OAComponentsSegment = {
+  SCHEMAS: "schemas",
+  RESPONSES: "responses",
+  PARAMETERS: "parameters",
+  EXAMPLES: "examples",
+  REQUEST_BODIES: "requestBodies",
+  HEADERS: "headers",
+  SECURITY_SCHEMES: "securitySchemes",
+  LINKS: "links",
+  CALLBACKS: "callbacks",
+  PATH_ITEMS: "pathItems"
+};
 
 // src/utils/oa-ref.js
 var import_js_format = require("@e22m4u/js-format");
-var OAComponentType = {
-  SCHEMA: "schema",
-  RESPONSE: "response",
-  PARAMETER: "parameter",
-  EXAMPLE: "example",
-  REQUEST_BODY: "requestBody",
-  HEADER: "header",
-  SECURITY_SCHEME: "securityScheme",
-  LINK: "link",
-  CALLBACK: "callback",
-  PATH_ITEM: "pathItem"
-};
-var OA_COMPONENT_TYPE_TO_KEY_MAP = {
-  [OAComponentType.SCHEMA]: "schemas",
-  [OAComponentType.RESPONSE]: "responses",
-  [OAComponentType.PARAMETER]: "parameters",
-  [OAComponentType.EXAMPLE]: "examples",
-  [OAComponentType.REQUEST_BODY]: "requestBodies",
-  [OAComponentType.HEADER]: "headers",
-  [OAComponentType.SECURITY_SCHEME]: "securitySchemes",
-  [OAComponentType.LINK]: "links",
-  [OAComponentType.CALLBACK]: "callbacks",
-  [OAComponentType.PATH_ITEM]: "pathItems"
-};
-function oaRef(name, type) {
+function oaRef(name, segment) {
   if (!name || typeof name !== "string") {
     throw new import_js_format.InvalidArgumentError(
       'Parameter "name" must be a non-empty String, but %v was given.',
       name
     );
   }
-  if (!type || typeof type !== "string") {
+  if (!Object.values(OAComponentsSegment).includes(segment)) {
     throw new import_js_format.InvalidArgumentError(
-      'Parameter "type" must be a non-empty String, but %v was given.',
-      type
+      'Parameter "segment" must be one of values: %l, but %v was given.',
+      Object.values(OAComponentsSegment),
+      segment
     );
   }
-  const key = OA_COMPONENT_TYPE_TO_KEY_MAP[type];
-  if (!key) {
-    throw new import_js_format.InvalidArgumentError("Component type %v is not supported.", type);
-  }
-  return { $ref: `#/components/${key}/${name}` };
+  return { $ref: `#/components/${segment}/${name}` };
 }
 __name(oaRef, "oaRef");
-var oaSchemaRef = /* @__PURE__ */ __name((name) => oaRef(name, OAComponentType.SCHEMA), "oaSchemaRef");
-var oaResponseRef = /* @__PURE__ */ __name((name) => oaRef(name, OAComponentType.RESPONSE), "oaResponseRef");
-var oaParameterRef = /* @__PURE__ */ __name((name) => oaRef(name, OAComponentType.PARAMETER), "oaParameterRef");
-var oaExampleRef = /* @__PURE__ */ __name((name) => oaRef(name, OAComponentType.EXAMPLE), "oaExampleRef");
-var oaRequestBodyRef = /* @__PURE__ */ __name((name) => oaRef(name, OAComponentType.REQUEST_BODY), "oaRequestBodyRef");
-var oaSecuritySchemeRef = /* @__PURE__ */ __name((name) => oaRef(name, OAComponentType.SECURITY_SCHEME), "oaSecuritySchemeRef");
-var oaLinkRef = /* @__PURE__ */ __name((name) => oaRef(name, OAComponentType.LINK), "oaLinkRef");
-var oaCallbackRef = /* @__PURE__ */ __name((name) => oaRef(name, OAComponentType.CALLBACK), "oaCallbackRef");
-var oaPathItemRef = /* @__PURE__ */ __name((name) => oaRef(name, OAComponentType.PATH_ITEM), "oaPathItemRef");
+var oaSchemaRef = /* @__PURE__ */ __name((name) => oaRef(name, OAComponentsSegment.SCHEMAS), "oaSchemaRef");
+var oaResponseRef = /* @__PURE__ */ __name((name) => oaRef(name, OAComponentsSegment.RESPONSES), "oaResponseRef");
+var oaParameterRef = /* @__PURE__ */ __name((name) => oaRef(name, OAComponentsSegment.PARAMETERS), "oaParameterRef");
+var oaExampleRef = /* @__PURE__ */ __name((name) => oaRef(name, OAComponentsSegment.EXAMPLES), "oaExampleRef");
+var oaRequestBodyRef = /* @__PURE__ */ __name((name) => oaRef(name, OAComponentsSegment.REQUEST_BODIES), "oaRequestBodyRef");
+var oaSecuritySchemeRef = /* @__PURE__ */ __name((name) => oaRef(name, OAComponentsSegment.SECURITY_SCHEMES), "oaSecuritySchemeRef");
+var oaLinkRef = /* @__PURE__ */ __name((name) => oaRef(name, OAComponentsSegment.LINKS), "oaLinkRef");
+var oaCallbackRef = /* @__PURE__ */ __name((name) => oaRef(name, OAComponentsSegment.CALLBACKS), "oaCallbackRef");
+var oaPathItemRef = /* @__PURE__ */ __name((name) => oaRef(name, OAComponentsSegment.PATH_ITEMS), "oaPathItemRef");
 
 // src/utils/join-path.js
 function joinPath(...segments) {
-  const path = segments.filter(Boolean).map((seg) => seg.replace(/(^\/|\/$)/g, "")).filter(Boolean).join("/");
+  const path = segments.filter((seg) => seg != void 0).map((seg) => String(seg).replace(/(^\/|\/$)/g, "")).filter(Boolean).join("/");
   return "/" + path;
 }
 __name(joinPath, "joinPath");
@@ -301,7 +285,10 @@ function validateShallowOADocumentObject(documentObject) {
 __name(validateShallowOADocumentObject, "validateShallowOADocumentObject");
 
 // src/oa-document-builder.js
-var _OADocumentBuilder = class _OADocumentBuilder extends import_js_service.Service {
+var OADocumentBuilder = class extends import_js_service.Service {
+  static {
+    __name(this, "OADocumentBuilder");
+  }
   /**
    * Document.
    *
@@ -361,35 +348,28 @@ var _OADocumentBuilder = class _OADocumentBuilder extends import_js_service.Serv
   /**
    * Define component.
    *
-   * @param {string} targetKey
-   * @param {string} componentKey
-   * @param {string} definitionLabel
+   * @param {string} segmentName
+   * @param {string} propertyName
    * @param {object} definition
    * @returns {this}
    */
-  _defineComponent(targetKey, componentKey, definitionLabel, definition) {
-    if (!targetKey || typeof targetKey !== "string") {
+  _defineComponent(segmentName, propertyName, definition) {
+    if (!Object.values(OAComponentsSegment).includes(segmentName)) {
       throw new import_js_format3.InvalidArgumentError(
-        'Property "targetKey" must be a non-empty String, but %v was given.',
-        targetKey
+        'Property "segmentName" must be one of values: %l, but %v was given.',
+        Object.values(OAComponentsSegment),
+        segmentName
       );
     }
-    if (!componentKey || typeof componentKey !== "string") {
+    if (!propertyName || typeof propertyName !== "string") {
       throw new import_js_format3.InvalidArgumentError(
-        'Property "componentKey" must be a non-empty String, but %v was given.',
-        componentKey
-      );
-    }
-    if (!definitionLabel || typeof definitionLabel !== "string") {
-      throw new import_js_format3.InvalidArgumentError(
-        'Property "definitionLabel" must be a non-empty String, but %v was given.',
-        definitionLabel
+        'Property "propertyName" must be a non-empty String, but %v was given.',
+        propertyName
       );
     }
     if (!definition || typeof definition !== "object" || Array.isArray(definition)) {
       throw new import_js_format3.InvalidArgumentError(
-        "%s Definition must be an Object, but %v was given.",
-        definitionLabel,
+        "Component definition must be an Object, but %v was given.",
         definition
       );
     }
@@ -399,140 +379,150 @@ var _OADocumentBuilder = class _OADocumentBuilder extends import_js_service.Serv
         definition.name
       );
     }
-    const component = definition[componentKey];
+    const component = definition[propertyName];
     if (!component || typeof component !== "object" || Array.isArray(component)) {
       throw new import_js_format3.InvalidArgumentError(
         "Property %v must be an Object, but %v was given.",
-        componentKey,
+        propertyName,
         component
       );
     }
     if (!this._document.components) {
       this._document.components = {};
     }
-    if (!this._document.components[targetKey]) {
-      this._document.components[targetKey] = {};
+    if (!this._document.components[segmentName]) {
+      this._document.components[segmentName] = {};
     }
-    this._document.components[targetKey][definition.name] = component;
+    this._document.components[segmentName][definition.name] = structuredClone(component);
     return this;
   }
   /**
    * Define schema component.
    *
-   * @param {import('./oa-document-builder.js').OASchemaComponentDefinition} schemaDef
+   * @param {object} schemaDef
    * @returns {this}
    */
   defineSchemaComponent(schemaDef) {
-    return this._defineComponent("schemas", "schema", "Schema", schemaDef);
+    return this._defineComponent(
+      OAComponentsSegment.SCHEMAS,
+      "schema",
+      schemaDef
+    );
   }
   /**
    * Define response component.
    *
-   * @param {import('./oa-document-builder.js').OAResponseComponentDefinition} responseDef
+   * @param {object} responseDef
    * @returns {this}
    */
   defineResponseComponent(responseDef) {
     return this._defineComponent(
-      "responses",
+      OAComponentsSegment.RESPONSES,
       "response",
-      "Response",
       responseDef
     );
   }
   /**
    * Define parameter component.
    *
-   * @param {import('./oa-document-builder.js').OAParameterComponentDefinition} parameterDef
+   * @param {object} parameterDef
    * @returns {this}
    */
   defineParameterComponent(parameterDef) {
     return this._defineComponent(
-      "parameters",
+      OAComponentsSegment.PARAMETERS,
       "parameter",
-      "Parameter",
       parameterDef
     );
   }
   /**
    * Define example component.
    *
-   * @param {import('./oa-document-builder.js').OAExampleComponentDefinition} exampleDef
+   * @param {object} exampleDef
    * @returns {this}
    */
   defineExampleComponent(exampleDef) {
-    return this._defineComponent("examples", "example", "Example", exampleDef);
+    return this._defineComponent(
+      OAComponentsSegment.EXAMPLES,
+      "example",
+      exampleDef
+    );
   }
   /**
    * Define request body component.
    *
-   * @param {import('./oa-document-builder.js').OARequestBodyComponentDefinition} requestBodyDef
+   * @param {object} requestBodyDef
    * @returns {this}
    */
   defineRequestBodyComponent(requestBodyDef) {
     return this._defineComponent(
-      "requestBodies",
+      OAComponentsSegment.REQUEST_BODIES,
       "requestBody",
-      "Request body",
       requestBodyDef
     );
   }
   /**
    * Define header component.
    *
-   * @param {import('./oa-document-builder.js').OAHeaderComponentDefinition} headerDef
+   * @param {object} headerDef
    * @returns {this}
    */
   defineHeaderComponent(headerDef) {
-    return this._defineComponent("headers", "header", "Header", headerDef);
+    return this._defineComponent(
+      OAComponentsSegment.HEADERS,
+      "header",
+      headerDef
+    );
   }
   /**
    * Define security scheme component.
    *
-   * @param {import('./oa-document-builder.js').OASecuritySchemeComponentDefinition} securitySchemeDef
+   * @param {object} securitySchemeDef
    * @returns {this}
    */
   defineSecuritySchemeComponent(securitySchemeDef) {
     return this._defineComponent(
-      "securitySchemes",
+      OAComponentsSegment.SECURITY_SCHEMES,
       "securityScheme",
-      "Security Scheme",
       securitySchemeDef
     );
   }
   /**
    * Define link component.
    *
-   * @param {import('./oa-document-builder.js').OALinkComponentDefinition} linkDef
+   * @param {object} linkDef
    * @returns {this}
    */
   defineLinkComponent(linkDef) {
-    return this._defineComponent("links", "link", "Link", linkDef);
+    return this._defineComponent(
+      OAComponentsSegment.LINKS,
+      "link",
+      linkDef
+    );
   }
   /**
    * Define callback component.
    *
-   * @param {import('./oa-document-builder.js').OACallbackComponentDefinition} callbackDef
+   * @param {object} callbackDef
    * @returns {this}
    */
   defineCallbackComponent(callbackDef) {
     return this._defineComponent(
-      "callbacks",
+      OAComponentsSegment.CALLBACKS,
       "callback",
-      "Callback",
       callbackDef
     );
   }
   /**
    * Define path item component.
    *
-   * @param {import('./oa-document-builder.js').OAPathItemComponentDefinition} pathItemDef
+   * @param {object} pathItemDef
    * @returns {this}
    */
   definePathItemComponent(pathItemDef) {
     return this._defineComponent(
-      "pathItems",
+      OAComponentsSegment.PATH_ITEMS,
       "pathItem",
-      "Path Item",
       pathItemDef
     );
   }
@@ -603,12 +593,22 @@ var _OADocumentBuilder = class _OADocumentBuilder extends import_js_service.Serv
   build() {
     return structuredClone(this._document);
   }
+  /**
+   * Build JSON.
+   *
+   * @param {string|number} [space]
+   * @returns {string}
+   */
+  buildJson(space = 0) {
+    return JSON.stringify(this._document, null, space);
+  }
 };
-__name(_OADocumentBuilder, "OADocumentBuilder");
-var OADocumentBuilder = _OADocumentBuilder;
 
 // src/oa-document-scope.js
-var _OADocumentScope = class _OADocumentScope {
+var OADocumentScope = class _OADocumentScope {
+  static {
+    __name(this, "OADocumentScope");
+  }
   /**
    * @param {object} rootBuilder
    * @param {object} [options]
@@ -754,21 +754,11 @@ var _OADocumentScope = class _OADocumentScope {
       tags: [...this.tags, ...options.tags || []]
     });
   }
-  /**
-   * Build.
-   *
-   * @returns {object}
-   */
-  build() {
-    return this.rootBuilder.build();
-  }
 };
-__name(_OADocumentScope, "OADocumentScope");
-var OADocumentScope = _OADocumentScope;
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   OAApiKeyLocation,
-  OAComponentType,
+  OAComponentsSegment,
   OADataFormat,
   OADataType,
   OADocumentBuilder,
@@ -778,7 +768,6 @@ var OADocumentScope = _OADocumentScope;
   OAParameterLocation,
   OAParameterStyle,
   OASecuritySchemeType,
-  OA_COMPONENT_TYPE_TO_KEY_MAP,
   OPENAPI_VERSION,
   oaCallbackRef,
   oaExampleRef,

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@e22m4u/js-openapi",
-  "version": "0.0.2",
+  "version": "0.0.3",
   "description": "JavaScript модуль для создания OpenAPI Документа",
   "author": "Mikhail Evstropov <e22m4u@yandex.ru>",
   "license": "MIT",
@@ -24,12 +24,12 @@
     "require": "./dist/cjs/index.cjs"
   },
   "engines": {
-    "node": ">=12"
+    "node": ">=18"
   },
   "scripts": {
     "lint": "tsc && eslint ./src",
     "lint:fix": "tsc && eslint ./src --fix",
-    "format": "prettier --write \"./src/**/*.js\"",
+    "format": "prettier --write \"./src/**/*.{js,ts}\"",
     "test": "npm run lint && c8 --reporter=text-summary mocha --bail",
     "test:coverage": "npm run lint && c8 --reporter=text mocha --bail",
     "build:cjs": "rimraf ./dist/cjs && node build-cjs.js",

src/constants.d.ts

@@ -2,3 +2,25 @@
  * OpenAPI version.
  */
 export declare const OPENAPI_VERSION: '3.1.0';
+
+/**
+ * Components segment.
+ *
+ * "#/components/{segment}/{name}"
+ *                  ^^^
+ */
+export declare const OAComponentsSegment: {
+  SCHEMAS: 'schemas';
+  RESPONSES: 'responses';
+  PARAMETERS: 'parameters';
+  EXAMPLES: 'examples';
+  REQUEST_BODIES: 'requestBodies';
+  HEADERS: 'headers';
+  SECURITY_SCHEMES: 'securitySchemes';
+  LINKS: 'links';
+  CALLBACKS: 'callbacks';
+  PATH_ITEMS: 'pathItems';
+};
+
+export type OAComponentsSegment =
+  (typeof OAComponentsSegment)[keyof typeof OAComponentsSegment];

src/constants.js

@@ -2,3 +2,22 @@
  * OpenAPI version.
  */
 export const OPENAPI_VERSION = '3.1.0';
+
+/**
+ * Components segment.
+ *
+ * "#/components/{segment}/{name}"
+ *                  ^^^
+ */
+export const OAComponentsSegment = {
+  SCHEMAS: 'schemas',
+  RESPONSES: 'responses',
+  PARAMETERS: 'parameters',
+  EXAMPLES: 'examples',
+  REQUEST_BODIES: 'requestBodies',
+  HEADERS: 'headers',
+  SECURITY_SCHEMES: 'securitySchemes',
+  LINKS: 'links',
+  CALLBACKS: 'callbacks',
+  PATH_ITEMS: 'pathItems',
+};

src/document-specification.d.ts

@@ -516,7 +516,7 @@ export type OASchemaPropertiesObject = {
  */
 export type OAWebhooksObject = {
   [name: string]: OAPathItemObject | OAReferenceObject | undefined;
-}
+};
 
 /**
  * Callbacks Object.

src/index.d.ts

@@ -3,4 +3,4 @@ export * from './oa-document-scope.js';
 export * from './oa-document-builder.js';
 export * from './document-specification.js';
 
-export * from './utils/oa-ref.js';
+export * from './utils/oa-ref.js';

src/oa-document-builder.d.ts

@@ -235,4 +235,11 @@ export declare class OADocumentBuilder extends Service {
    * Build.
    */
   build(): OADocumentObject;
+
+  /**
+   * Build JSON.
+   *
+   * @param space
+   */
+  buildJson(space?: string | number): string;
 }

src/oa-document-builder.js

@@ -1,8 +1,8 @@
-import {OPENAPI_VERSION} from './constants.js';
 import {OADocumentScope} from './oa-document-scope.js';
 import {InvalidArgumentError} from '@e22m4u/js-format';
 import {OAOperationMethod} from './document-specification.js';
 import {isServiceContainer, Service} from '@e22m4u/js-service';
+import {OAComponentsSegment, OPENAPI_VERSION} from './constants.js';
 import {validateShallowOADocumentObject} from './document-validators.js';
 
 /**
@@ -94,35 +94,27 @@ export class OADocumentBuilder extends Service {
   /**
    * Define component.
    *
-   * @param {string} targetKey
-   * @param {string} componentKey
-   * @param {string} definitionLabel
+   * @param {string} segmentName
+   * @param {string} propertyName
    * @param {object} definition
    * @returns {this}
    */
-  _defineComponent(targetKey, componentKey, definitionLabel, definition) {
-    // targetKey
-    if (!targetKey || typeof targetKey !== 'string') {
+  _defineComponent(segmentName, propertyName, definition) {
+    // segmentName
+    if (!Object.values(OAComponentsSegment).includes(segmentName)) {
       throw new InvalidArgumentError(
-        'Property "targetKey" must be a non-empty String, ' +
+        'Property "segmentName" must be one of values: %l, ' +
           'but %v was given.',
-        targetKey,
+        Object.values(OAComponentsSegment),
+        segmentName,
       );
     }
-    // componentKey
-    if (!componentKey || typeof componentKey !== 'string') {
+    // propertyName
+    if (!propertyName || typeof propertyName !== 'string') {
       throw new InvalidArgumentError(
-        'Property "componentKey" must be a non-empty String, ' +
+        'Property "propertyName" must be a non-empty String, ' +
           'but %v was given.',
-        componentKey,
-      );
-    }
-    // definitionLabel
-    if (!definitionLabel || typeof definitionLabel !== 'string') {
-      throw new InvalidArgumentError(
-        'Property "definitionLabel" must be a non-empty String, ' +
-          'but %v was given.',
-        definitionLabel,
+        propertyName,
       );
     }
     // definition
@@ -132,8 +124,7 @@ export class OADocumentBuilder extends Service {
       Array.isArray(definition)
     ) {
       throw new InvalidArgumentError(
-        '%s Definition must be an Object, but %v was given.',
-        definitionLabel,
+        'Component definition must be an Object, but %v was given.',
         definition,
       );
     }
@@ -145,7 +136,7 @@ export class OADocumentBuilder extends Service {
       );
     }
     // definition[componentKey]
-    const component = definition[componentKey];
+    const component = definition[propertyName];
     if (
       !component ||
       typeof component !== 'object' ||
@@ -153,41 +144,45 @@ export class OADocumentBuilder extends Service {
     ) {
       throw new InvalidArgumentError(
         'Property %v must be an Object, but %v was given.',
-        componentKey,
+        propertyName,
         component,
       );
     }
     if (!this._document.components) {
       this._document.components = {};
     }
-    if (!this._document.components[targetKey]) {
-      this._document.components[targetKey] = {};
+    if (!this._document.components[segmentName]) {
+      this._document.components[segmentName] = {};
     }
-    this._document.components[targetKey][definition.name] = component;
+    this._document.components[segmentName][definition.name] =
+      structuredClone(component);
     return this;
   }
 
   /**
    * Define schema component.
    *
-   * @param {import('./oa-document-builder.js').OASchemaComponentDefinition} schemaDef
+   * @param {object} schemaDef
    * @returns {this}
    */
   defineSchemaComponent(schemaDef) {
-    return this._defineComponent('schemas', 'schema', 'Schema', schemaDef);
+    return this._defineComponent(
+      OAComponentsSegment.SCHEMAS,
+      'schema',
+      schemaDef,
+    );
   }
 
   /**
    * Define response component.
    *
-   * @param {import('./oa-document-builder.js').OAResponseComponentDefinition} responseDef
+   * @param {object} responseDef
    * @returns {this}
    */
   defineResponseComponent(responseDef) {
     return this._defineComponent(
-      'responses',
+      OAComponentsSegment.RESPONSES,
       'response',
-      'Response',
       responseDef,
     );
   }
@@ -195,14 +190,13 @@ export class OADocumentBuilder extends Service {
   /**
    * Define parameter component.
    *
-   * @param {import('./oa-document-builder.js').OAParameterComponentDefinition} parameterDef
+   * @param {object} parameterDef
    * @returns {this}
    */
   defineParameterComponent(parameterDef) {
     return this._defineComponent(
-      'parameters',
+      OAComponentsSegment.PARAMETERS,
       'parameter',
-      'Parameter',
       parameterDef,
     );
   }
@@ -210,24 +204,27 @@ export class OADocumentBuilder extends Service {
   /**
    * Define example component.
    *
-   * @param {import('./oa-document-builder.js').OAExampleComponentDefinition} exampleDef
+   * @param {object} exampleDef
    * @returns {this}
    */
   defineExampleComponent(exampleDef) {
-    return this._defineComponent('examples', 'example', 'Example', exampleDef);
+    return this._defineComponent(
+      OAComponentsSegment.EXAMPLES,
+      'example',
+      exampleDef,
+    );
   }
 
   /**
    * Define request body component.
    *
-   * @param {import('./oa-document-builder.js').OARequestBodyComponentDefinition} requestBodyDef
+   * @param {object} requestBodyDef
    * @returns {this}
    */
   defineRequestBodyComponent(requestBodyDef) {
     return this._defineComponent(
-      'requestBodies',
+      OAComponentsSegment.REQUEST_BODIES,
       'requestBody',
-      'Request body',
       requestBodyDef,
     );
   }
@@ -235,24 +232,27 @@ export class OADocumentBuilder extends Service {
   /**
    * Define header component.
    *
-   * @param {import('./oa-document-builder.js').OAHeaderComponentDefinition} headerDef
+   * @param {object} headerDef
    * @returns {this}
    */
   defineHeaderComponent(headerDef) {
-    return this._defineComponent('headers', 'header', 'Header', headerDef);
+    return this._defineComponent(
+      OAComponentsSegment.HEADERS,
+      'header',
+      headerDef,
+    );
   }
 
   /**
    * Define security scheme component.
    *
-   * @param {import('./oa-document-builder.js').OASecuritySchemeComponentDefinition} securitySchemeDef
+   * @param {object} securitySchemeDef
    * @returns {this}
    */
   defineSecuritySchemeComponent(securitySchemeDef) {
     return this._defineComponent(
-      'securitySchemes',
+      OAComponentsSegment.SECURITY_SCHEMES,
       'securityScheme',
-      'Security Scheme',
       securitySchemeDef,
     );
   }
@@ -260,24 +260,28 @@ export class OADocumentBuilder extends Service {
   /**
    * Define link component.
    *
-   * @param {import('./oa-document-builder.js').OALinkComponentDefinition} linkDef
+   * @param {object} linkDef
    * @returns {this}
    */
   defineLinkComponent(linkDef) {
-    return this._defineComponent('links', 'link', 'Link', linkDef);
+    /* prettier-ignore */
+    return this._defineComponent(
+      OAComponentsSegment.LINKS,
+      'link',
+      linkDef,
+    );
   }
 
   /**
    * Define callback component.
    *
-   * @param {import('./oa-document-builder.js').OACallbackComponentDefinition} callbackDef
+   * @param {object} callbackDef
    * @returns {this}
    */
   defineCallbackComponent(callbackDef) {
     return this._defineComponent(
-      'callbacks',
+      OAComponentsSegment.CALLBACKS,
       'callback',
-      'Callback',
       callbackDef,
     );
   }
@@ -285,14 +289,13 @@ export class OADocumentBuilder extends Service {
   /**
    * Define path item component.
    *
-   * @param {import('./oa-document-builder.js').OAPathItemComponentDefinition} pathItemDef
+   * @param {object} pathItemDef
    * @returns {this}
    */
   definePathItemComponent(pathItemDef) {
     return this._defineComponent(
-      'pathItems',
+      OAComponentsSegment.PATH_ITEMS,
       'pathItem',
-      'Path Item',
       pathItemDef,
     );
   }
@@ -378,4 +381,14 @@ export class OADocumentBuilder extends Service {
   build() {
     return structuredClone(this._document);
   }
+
+  /**
+   * Build JSON.
+   *
+   * @param {string|number} [space]
+   * @returns {string}
+   */
+  buildJson(space = 0) {
+    return JSON.stringify(this._document, null, space);
+  }
 }

src/oa-document-scope.d.ts

@@ -1,5 +1,3 @@
-import {OADocumentObject} from './document-specification.js';
-
 import {
   OADocumentBuilder,
   OAOperationDefinition,
@@ -36,9 +34,4 @@ export declare class OADocumentScope {
    * @param options
    */
   createScope(options?: OADocumentScopeOptions): OADocumentScope;
-
-  /**
-   * Build.
-   */
-  build(): OADocumentObject;
 }

src/oa-document-scope.js

@@ -178,13 +178,4 @@ export class OADocumentScope {
       tags: [...this.tags, ...(options.tags || [])],
     });
   }
-
-  /**
-   * Build.
-   *
-   * @returns {object}
-   */
-  build() {
-    return this.rootBuilder.build();
-  }
 }

src/utils/index.d.ts

@@ -1,2 +1,2 @@
 export * from './oa-ref.js';
-export * from './join-path.js';
+export * from './join-path.js';

src/utils/join-path.d.ts

@@ -3,4 +3,4 @@
  *
  * @param segments
  */
-export declare function joinPath(...segments: string[]): string;
+export declare function joinPath(...segments: (string | number)[]): string;

src/utils/join-path.js

@@ -6,8 +6,8 @@
  */
 export function joinPath(...segments) {
   const path = segments
-    .filter(Boolean)
-    .map(seg => seg.replace(/(^\/|\/$)/g, ''))
+    .filter(seg => seg != undefined)
+    .map(seg => String(seg).replace(/(^\/|\/$)/g, ''))
     .filter(Boolean)
     .join('/');
   return '/' + path;

src/utils/join-path.spec.js

@@ -61,4 +61,9 @@ describe('joinPath', function () {
     const result = joinPath('api/v1', 'users');
     expect(result).to.be.eq('/api/v1/users');
   });
+
+  it('should convert number arguments to string segments', function () {
+    const result = joinPath(-10, 0, 10);
+    expect(result).to.be.eq('/-10/0/10');
+  });
 });

src/utils/oa-ref.d.ts

@@ -1,40 +1,22 @@
+import {OAComponentsSegment} from '../constants.js';
 import {OAReferenceObject} from '../document-specification.js';
 
-/**
- * Component type.
- */
-export declare const OAComponentType: {
-  SCHEMA: 'schema';
-  RESPONSE: 'response';
-  PARAMETER: 'parameter';
-  EXAMPLE: 'example';
-  REQUEST_BODY: 'requestBody';
-  HEADER: 'header';
-  SECURITY_SCHEME: 'securityScheme';
-  LINK: 'link';
-  CALLBACK: 'callback';
-  PATH_ITEM: 'pathItem';
-};
-
-export type OAComponentType =
-  (typeof OAComponentType)[keyof typeof OAComponentType];
-
 /**
  * Create the Reference Object.
  *
  * Example:
  *
  * ```js
- * oaRef('User', OAComponentType.SCHEMA);
+ * oaRef('User', OAComponentsSegment.SCHEMAS);
  * // {"$ref": "#/components/schemas/User"}
  * ```
  *
  * @param name
- * @param type
+ * @param segment
  */
 export declare function oaRef(
   name: string,
-  type: OAComponentType,
+  segment: OAComponentsSegment,
 ): OAReferenceObject;
 
 /* aliases */

src/utils/oa-ref.js

@@ -1,80 +1,48 @@
+import {OAComponentsSegment} from '../constants.js';
 import {InvalidArgumentError} from '@e22m4u/js-format';
 
-/**
- * Component type.
- */
-export const OAComponentType = {
-  SCHEMA: 'schema',
-  RESPONSE: 'response',
-  PARAMETER: 'parameter',
-  EXAMPLE: 'example',
-  REQUEST_BODY: 'requestBody',
-  HEADER: 'header',
-  SECURITY_SCHEME: 'securityScheme',
-  LINK: 'link',
-  CALLBACK: 'callback',
-  PATH_ITEM: 'pathItem',
-};
-
-/**
- * Component type to key map.
- */
-export const OA_COMPONENT_TYPE_TO_KEY_MAP = {
-  [OAComponentType.SCHEMA]: 'schemas',
-  [OAComponentType.RESPONSE]: 'responses',
-  [OAComponentType.PARAMETER]: 'parameters',
-  [OAComponentType.EXAMPLE]: 'examples',
-  [OAComponentType.REQUEST_BODY]: 'requestBodies',
-  [OAComponentType.HEADER]: 'headers',
-  [OAComponentType.SECURITY_SCHEME]: 'securitySchemes',
-  [OAComponentType.LINK]: 'links',
-  [OAComponentType.CALLBACK]: 'callbacks',
-  [OAComponentType.PATH_ITEM]: 'pathItems',
-};
-
 /**
  * Create the Reference Object.
  *
  * Example:
  *
  * ```js
- * oaRef('User', OAComponentType.SCHEMA);
+ * oaRef('User', OAComponentsSegment.SCHEMAS);
  * // {"$ref": "#/components/schemas/User"}
  * ```
  *
  * @param {string} name
- * @param {string} type
+ * @param {string} segment
  * @returns {object}
  */
-export function oaRef(name, type) {
+export function oaRef(name, segment) {
   if (!name || typeof name !== 'string') {
     throw new InvalidArgumentError(
       'Parameter "name" must be a non-empty String, but %v was given.',
       name,
     );
   }
-  if (!type || typeof type !== 'string') {
+  if (!Object.values(OAComponentsSegment).includes(segment)) {
     throw new InvalidArgumentError(
-      'Parameter "type" must be a non-empty String, but %v was given.',
-      type,
+      'Parameter "segment" must be one of values: %l, but %v was given.',
+      Object.values(OAComponentsSegment),
+      segment,
     );
   }
-  const key = OA_COMPONENT_TYPE_TO_KEY_MAP[type];
-  if (!key) {
-    throw new InvalidArgumentError('Component type %v is not supported.', type);
-  }
-  return {$ref: `#/components/${key}/${name}`};
+  return {$ref: `#/components/${segment}/${name}`};
 }
 
 /* aliases */
-export const oaSchemaRef = name => oaRef(name, OAComponentType.SCHEMA);
-export const oaResponseRef = name => oaRef(name, OAComponentType.RESPONSE);
-export const oaParameterRef = name => oaRef(name, OAComponentType.PARAMETER);
-export const oaExampleRef = name => oaRef(name, OAComponentType.EXAMPLE);
+export const oaSchemaRef = name => oaRef(name, OAComponentsSegment.SCHEMAS);
+export const oaResponseRef = name => oaRef(name, OAComponentsSegment.RESPONSES);
+export const oaParameterRef = name =>
+  oaRef(name, OAComponentsSegment.PARAMETERS);
+export const oaExampleRef = name => oaRef(name, OAComponentsSegment.EXAMPLES);
 export const oaRequestBodyRef = name =>
-  oaRef(name, OAComponentType.REQUEST_BODY);
+  oaRef(name, OAComponentsSegment.REQUEST_BODIES);
 export const oaSecuritySchemeRef = name =>
-  oaRef(name, OAComponentType.SECURITY_SCHEME);
-export const oaLinkRef = name => oaRef(name, OAComponentType.LINK);
-export const oaCallbackRef = name => oaRef(name, OAComponentType.CALLBACK);
-export const oaPathItemRef = name => oaRef(name, OAComponentType.PATH_ITEM);
+  oaRef(name, OAComponentsSegment.SECURITY_SCHEMES);
+export const oaLinkRef = name => oaRef(name, OAComponentsSegment.LINKS);
+export const oaCallbackRef = name => oaRef(name, OAComponentsSegment.CALLBACKS);
+export const oaPathItemRef = name =>
+  oaRef(name, OAComponentsSegment.PATH_ITEMS);

src/utils/oa-ref.spec.js

@@ -1,5 +1,6 @@
 import {expect} from 'chai';
 import {format} from '@e22m4u/js-format';
+import {OAComponentsSegment} from '../constants.js';
 
 import {
   oaRef,
@@ -10,15 +11,13 @@ import {
   oaPathItemRef,
   oaCallbackRef,
   oaParameterRef,
-  OAComponentType,
   oaRequestBodyRef,
   oaSecuritySchemeRef,
-  OA_COMPONENT_TYPE_TO_KEY_MAP,
 } from './oa-ref.js';
 
 describe('oaRef', function () {
   it('should require the "name" parameter to be a non-empty String', function () {
-    const throwable = v => () => oaRef(v, OAComponentType.SCHEMA);
+    const throwable = v => () => oaRef(v, OAComponentsSegment.SCHEMAS);
     const error = s =>
       format(
         'Parameter "name" must be a non-empty String, but %s was given.',
@@ -36,13 +35,16 @@ describe('oaRef', function () {
     throwable('str')();
   });
 
-  it('should require the "type" parameter to be a non-empty String', function () {
+  it('should require the "segment" parameter to be a components segment', function () {
     const throwable = v => () => oaRef('Model', v);
+    const segments = Object.values(OAComponentsSegment);
     const error = s =>
       format(
-        'Parameter "type" must be a non-empty String, but %s was given.',
+        'Parameter "segment" must be one of values: %l, but %s was given.',
+        segments,
         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'));
@@ -52,31 +54,26 @@ describe('oaRef', function () {
     expect(throwable({})).to.throw(error('Object'));
     expect(throwable(undefined)).to.throw(error('undefined'));
     expect(throwable(null)).to.throw(error('null'));
-    throwable(OAComponentType.SCHEMA)();
+    segments.forEach(segment => throwable(segment)());
   });
 
-  it('should throw an error if a given type is not supported', function () {
-    const throwable = () => oaRef('name', 'unknown');
-    expect(throwable).to.throw('Component type "unknown" is not supported.');
-  });
-
-  it('should set the "name" argument to the component path', function () {
-    expect(oaRef('Model', OAComponentType.SCHEMA)).to.be.eql({
+  it('should set the "name" argument to the reference path', function () {
+    expect(oaRef('Model', OAComponentsSegment.SCHEMAS)).to.be.eql({
       $ref: '#/components/schemas/Model',
     });
   });
 
-  it('should set the correct segment by a given component type', function () {
-    Object.keys(OA_COMPONENT_TYPE_TO_KEY_MAP).forEach(type => {
-      const key = OA_COMPONENT_TYPE_TO_KEY_MAP[type];
-      expect(oaRef('name', type)).to.be.eql({
-        $ref: `#/components/${key}/name`,
+  it('should set the "segment" argument to the reference path', function () {
+    const segments = Object.values(OAComponentsSegment);
+    segments.forEach(segment => {
+      expect(oaRef('name', segment)).to.be.eql({
+        $ref: `#/components/${segment}/name`,
       });
     });
   });
 
   describe('aliases', function () {
-    it('should use the correct type', function () {
+    it('should use the correct segment', function () {
       const aliasesToResultMap = [
         [oaSchemaRef, {$ref: '#/components/schemas/name'}],
         [oaResponseRef, {$ref: '#/components/responses/name'}],