@api-client/core 0.19.19 → 0.19.20

package/src/modeling/generators/oas_312/OasSchemaGenerator.ts

@@ -0,0 +1,322 @@
+import type { ReferenceObject, SchemaObject } from './types.js'
+import { AssociationWebBindings, PropertyWebBindings } from '../../Bindings.js'
+import type { DomainEntity } from '../../DomainEntity.js'
+import type { DomainProperty } from '../../DomainProperty.js'
+import { SemanticType } from '../../Semantics.js'
+
+interface SemanticExtension {
+  'x-api-now-semantics'?: Record<string, unknown>
+}
+
+function getSemanticName(id: string): string {
+  return id.split('#')[1]
+}
+
+export class OasSchemaGenerator {
+  private memorySchemas: Record<string, SchemaObject> = {}
+  private memoryNames: Record<string, string> = {}
+
+  #hasFileUpload = false
+
+  /**
+   * A flag that determines whether any of the properties has the `FileURL` or `ImageURL` semantic.
+   */
+  get hasFileUpload(): boolean {
+    return this.#hasFileUpload
+  }
+
+  /**
+   * Retrieves the dictionary of all processed OAS JSON schemas.
+   */
+  public getSchemas(): Record<string, SchemaObject> {
+    const result: Record<string, SchemaObject> = {}
+    for (const [key, value] of Object.entries(this.memorySchemas)) {
+      result[this.memoryNames[key]] = value
+    }
+    return result
+  }
+
+  /**
+   * Generates schemas recursively for an entity and returns the $ref pointing to the root representation.
+   * @param entity
+   */
+  public generateRootRef(entity: DomainEntity): ReferenceObject {
+    this.generateEntity(entity)
+    return { $ref: `#/components/schemas/${this.generateSchemaKey(entity)}` }
+  }
+
+  /**
+   * Generates a schema key for an entity.
+   */
+  public generateSchemaKey(entity: DomainEntity): string {
+    return entity.info.name || 'entity ' + entity.key
+  }
+
+  private generateEntity(entity: DomainEntity): void {
+    if (this.memorySchemas[entity.key]) {
+      return // Already processed or processing
+    }
+
+    // Preemptively assign to avoid infinite recursion over bidirectional associations
+    const schema: SchemaObject & SemanticExtension = {
+      type: 'object',
+      properties: {},
+      required: [],
+    }
+    this.memorySchemas[entity.key] = schema
+    const schemaKey = this.generateSchemaKey(entity)
+    this.memoryNames[entity.key] = schemaKey
+    if (entity.info.displayName) {
+      schema.title = entity.info.displayName
+    }
+    if (entity.info.description) {
+      schema.description = entity.info.description
+    }
+
+    if (entity.semantics.length > 0) {
+      schema['x-api-now-semantics'] = {}
+      for (const semantic of entity.semantics) {
+        schema['x-api-now-semantics'][getSemanticName(semantic.id)] = semantic.config ? semantic.config : {}
+      }
+    }
+
+    const required: string[] = []
+
+    for (const prop of entity.properties) {
+      if (prop.required && !prop.readOnly) {
+        required.push(prop.info.name || prop.key)
+      }
+      if (!schema.properties) {
+        schema.properties = {}
+      }
+      const webBindings = prop.readBinding('web') as PropertyWebBindings | undefined
+      if (webBindings?.hidden) {
+        continue
+      }
+      schema.properties[prop.info.name || prop.key] = this.mapPropertyBase(prop, webBindings)
+    }
+
+    for (const assoc of entity.associations) {
+      const bindings = assoc.readBinding('web') as AssociationWebBindings | undefined
+      if (bindings?.hidden) {
+        continue
+      }
+
+      const targets = Array.from(assoc.listTargets())
+      if (targets.length === 0) continue
+
+      const linked = assoc.schema?.linked === true
+      const targetRefs: (SchemaObject | ReferenceObject)[] = []
+
+      for (const targetEntity of targets) {
+        if (linked) {
+          // When an entity is linked then we treat it as a regular property, which value is a key to
+          // the target entity. The consuming application has to construct the endpoint manually.
+          const targetName = targetEntity.info.displayName || targetEntity.info.name || targetEntity.key
+          targetRefs.push({
+            type: 'string',
+            description: `The ID of the linked ${targetName}.`,
+          })
+        } else {
+          // If not linked, embed the resource as a reference to the schema.
+          if (targetEntity !== entity) {
+            this.generateEntity(targetEntity)
+          }
+          targetRefs.push({ $ref: `#/components/schemas/${this.generateSchemaKey(targetEntity)}` })
+        }
+      }
+
+      let assocSchema: SchemaObject | ReferenceObject
+      if (targetRefs.length > 1) {
+        const unionType = assoc.schema?.unionType || 'anyOf'
+        if (unionType === 'oneOf') {
+          assocSchema = { oneOf: targetRefs }
+        } else if (unionType === 'allOf') {
+          assocSchema = { allOf: targetRefs }
+        } else {
+          assocSchema = { anyOf: targetRefs }
+        }
+      } else {
+        assocSchema = targetRefs[0]
+      }
+
+      const propName = assoc.info.name || assoc.key
+      if (!schema.properties) {
+        schema.properties = {}
+      }
+
+      if (assoc.multiple) {
+        schema.properties[propName] = {
+          type: 'array',
+          items: assocSchema,
+        }
+      } else {
+        schema.properties[propName] = assocSchema
+      }
+    }
+
+    if (required.length > 0) {
+      schema.required = required
+    } else {
+      delete schema.required
+    }
+    const example = entity.toExample('application/json', {
+      // renderExamples: true,
+      renderMocked: false,
+      renderOptional: true,
+    })
+    if (example) {
+      if (typeof example === 'string') {
+        try {
+          schema.example = JSON.parse(example)
+        } catch {
+          schema.example = example
+        }
+      } else {
+        schema.example = example
+      }
+    }
+  }
+
+  private mapPropertyBase(prop: DomainProperty, webBindings?: PropertyWebBindings): SchemaObject | ReferenceObject {
+    const base: SchemaObject & SemanticExtension = {}
+
+    if (prop.readOnly) {
+      base.readOnly = true
+    }
+
+    if (prop.writeOnly) {
+      base.writeOnly = true
+    }
+
+    if (prop.deprecated) {
+      base.deprecated = true
+    }
+
+    if (prop.schema) {
+      if (prop.schema.minimum !== undefined) {
+        if (prop.schema.exclusiveMinimum) {
+          base.exclusiveMinimum = prop.schema.minimum
+        } else {
+          base.minimum = prop.schema.minimum
+        }
+      }
+      if (prop.schema.maximum !== undefined) {
+        if (prop.schema.exclusiveMaximum) {
+          base.exclusiveMaximum = prop.schema.maximum
+        } else {
+          base.maximum = prop.schema.maximum
+        }
+      }
+      if (prop.schema.pattern) {
+        base.pattern = prop.schema.pattern
+      }
+      if (prop.schema.enum) {
+        base.enum = [...prop.schema.enum]
+      }
+      if (prop.schema.defaultValue?.value !== undefined) {
+        base.default = prop.schema.defaultValue.value
+      }
+      if (prop.schema.examples && prop.schema.examples.length > 0) {
+        // AMF incorrectly ignores `examples` property in JSON Schema in OAS 3.1 version.
+        // A temporary workaround is to set the `example` property instead of `examples`.
+        // const examples: ExampleObject[] = []
+        // for (const example of prop.schema.examples) {
+        //   const value: ExampleObject = {
+        //     value: example,
+        //   }
+        //   examples.push(value)
+        // }
+        // base.examples = examples
+        base.example = prop.schema.examples[0]
+      }
+    }
+
+    if (prop.info.displayName) {
+      base.title = prop.info.displayName
+    }
+
+    if (prop.info.description) {
+      base.description = prop.info.description
+    }
+
+    if (prop.hasSemantic(SemanticType.Password)) {
+      base.format = 'password'
+    }
+
+    if (webBindings?.xml) {
+      base.xml = { ...webBindings.xml }
+    }
+
+    if (prop.semantics.length > 0) {
+      base['x-api-now-semantics'] = {}
+      for (const semantic of prop.semantics) {
+        if (!this.#hasFileUpload && (semantic.id === SemanticType.FileURL || semantic.id === SemanticType.ImageURL)) {
+          this.#hasFileUpload = true
+        }
+        base['x-api-now-semantics'][getSemanticName(semantic.id)] = semantic.config ? semantic.config : {}
+      }
+    }
+
+    switch (prop.type) {
+      case 'string':
+        base.type = 'string'
+        break
+      case 'number':
+        if (webBindings?.format === 'int32' || webBindings?.format === 'int64') {
+          base.type = 'integer'
+        } else {
+          base.type = 'number'
+        }
+        if (prop.schema?.multipleOf !== undefined) {
+          base.multipleOf = prop.schema.multipleOf
+        }
+        break
+      case 'boolean':
+        base.type = 'boolean'
+        break
+      case 'date':
+        base.type = 'string'
+        base.format = 'date'
+        break
+      case 'datetime':
+        base.type = 'string'
+        base.format = 'date-time'
+        break
+      case 'time':
+        base.type = 'string'
+        base.format = 'time'
+        break
+      case 'binary':
+        base.type = 'string'
+        if (webBindings?.format) {
+          base.format = webBindings.format
+        } else {
+          base.format = 'binary'
+        }
+        if (webBindings?.fileTypes && webBindings.fileTypes.length > 0) {
+          const typesStr = webBindings.fileTypes.join(', ')
+          // Standard JSON Schema keyword for media wrapping (single value string usually,
+          // but some tools handle comma separated)
+          base.contentMediaType = webBindings.fileTypes.length === 1 ? webBindings.fileTypes[0] : typesStr
+          // Vendor extension for tools supporting multiple explicit arrays
+          // ;(base as any)['x-file-types'] = webBindings.fileTypes
+          // Append to description so viewers can always see the requirements natively
+          const typesDesc = `**Allowed file types:** ${typesStr}`
+          base.description = base.description ? `${base.description}\n\n${typesDesc}` : typesDesc
+        }
+        break
+      default:
+        base.type = 'string' // fallback
+    }
+
+    if (prop.multiple) {
+      return {
+        type: 'array',
+        items: base,
+      }
+    }
+
+    return base
+  }
+}