@api-client/core 0.19.18 → 0.19.20

package/src/modeling/generators/oas_320/OasGenerator.ts

@@ -0,0 +1,359 @@
+import type {
+  InfoObject,
+  MediaTypeObject,
+  OpenApi320,
+  ParameterObject,
+  PathItemObject,
+  PathsObject,
+  ReferenceObject,
+  RequestBodyObject,
+  SecurityRequirementObject,
+  SecuritySchemeObject,
+  OperationObject,
+} from './types.js'
+import type { ApiModel } from '../../ApiModel.js'
+import type { Action } from '../../actions/Action.js'
+import { OasSchemaGenerator } from './OasSchemaGenerator.js'
+import type { MatchUserRoleAccessRule } from '../../rules/MatchUserRole.js'
+
+export class OasGenerator {
+  /**
+   * @param model The API model to generate OAS for.
+   */
+  constructor(private model: ApiModel) {}
+
+  generate(): OpenApi320 {
+    const { domain } = this.model
+    if (!domain) {
+      throw new Error('Data domain is required for OAS generation')
+    }
+    const schemaGen = new OasSchemaGenerator(domain)
+    const paths = this.generatePaths(schemaGen)
+
+    const result: OpenApi320 = {
+      openapi: '3.2.0',
+      info: this.generateInfo(),
+      paths: paths,
+      components: {
+        schemas: schemaGen.getSchemas(),
+        securitySchemes: this.generateSecuritySchemes(),
+      },
+    }
+
+    if (this.model.accessRule && this.model.accessRule.length > 0) {
+      // Security requirements are determined by how the session is transported.
+      // OAS allows logical OR by adding separate objects in the global security array.
+      const securityRequirements: SecurityRequirementObject[] = []
+
+      if (this.model.session?.jwt?.enabled) {
+        securityRequirements.push({ BearerAuth: [] })
+      }
+      if (this.model.session?.cookie?.enabled) {
+        securityRequirements.push({ CookieAuth: [] })
+      }
+
+      if (securityRequirements.length > 0) {
+        result.security = securityRequirements
+      }
+    }
+
+    return result
+  }
+
+  private generateInfo(): InfoObject {
+    const info: InfoObject = {
+      title: this.model.info.displayName || this.model.info.name || 'API',
+      version: this.model.info.version || '1.0.0',
+    }
+
+    if (this.model.info.description) {
+      info.description = this.model.info.description
+    }
+
+    if (this.model.termsOfService) {
+      info.termsOfService = this.model.termsOfService
+    }
+
+    if (this.model.contact) {
+      info.contact = { ...this.model.contact }
+    }
+
+    if (this.model.license) {
+      info.license = { ...this.model.license }
+    }
+
+    return info
+  }
+
+  private generateSecuritySchemes(): Record<string, ReferenceObject | SecuritySchemeObject> {
+    const schemes: Record<string, ReferenceObject | SecuritySchemeObject> = {}
+
+    // OpenAPI doesn't have a native "Username/Password" strategy (except via OAuth2 flows).
+    // The actual security required to make calls to the API is defined by the Session transport.
+    if (this.model.session) {
+      if (this.model.session.jwt?.enabled) {
+        schemes['BearerAuth'] = {
+          type: 'http',
+          scheme: 'bearer',
+          bearerFormat: 'JWT',
+          description: 'JWT authorization obtained after trading Username/Password credentials',
+        }
+      }
+      if (this.model.session.cookie?.enabled) {
+        schemes['CookieAuth'] = {
+          type: 'apiKey',
+          in: 'cookie',
+          name: this.model.session.cookie.name || 'as',
+          description: 'Session cookie obtained after authenticating',
+        }
+      }
+    }
+
+    return schemes
+  }
+
+  private generatePaths(schemaGen: OasSchemaGenerator): PathsObject {
+    const paths: PathsObject = {}
+
+    // Depending on the configured session transports, the API will expose different login endpoints.
+    if (this.model.authentication?.strategy === 'UsernamePassword') {
+      if (this.model.session?.jwt?.enabled) {
+        paths['/auth/token'] = {
+          post: {
+            operationId: 'session_token_exchange',
+            summary: 'Exchange credentials for a JWT token',
+            requestBody: {
+              required: true,
+              content: {
+                'application/json': {
+                  schema: {
+                    type: 'object',
+                    properties: {
+                      username: { type: 'string' },
+                      password: { type: 'string', format: 'password' },
+                    },
+                    required: ['username', 'password'],
+                  },
+                },
+              },
+            },
+            responses: {
+              '200': {
+                description: 'Returns the JSON Web Token',
+                content: {
+                  'application/json': {
+                    schema: {
+                      type: 'object',
+                      properties: {
+                        token: { type: 'string' },
+                      },
+                      required: ['token'],
+                    },
+                  },
+                },
+              },
+              '401': { description: 'Invalid credentials' },
+            },
+            security: [],
+          },
+        }
+
+        paths['/auth/token/{token}'] = {
+          delete: {
+            operationId: 'session_token_revoke',
+            summary: 'Revoke a specific JWT token',
+            parameters: [
+              {
+                name: 'token',
+                in: 'path',
+                required: true,
+                schema: { type: 'string' },
+                description: 'The session token to revoke',
+              },
+            ],
+            responses: {
+              '204': { description: 'Token revoked successfully' },
+              '401': { description: 'Unauthenticated' },
+            },
+            security: [],
+          },
+        }
+      }
+
+      if (this.model.session?.cookie?.enabled) {
+        paths['/auth/cookie'] = {
+          post: {
+            operationId: 'session_cookie_exchange',
+            summary: 'Obtain a session cookie and redirect to a web app',
+            requestBody: {
+              required: true,
+              content: {
+                'application/json': {
+                  schema: {
+                    type: 'object',
+                    properties: {
+                      username: { type: 'string' },
+                      password: { type: 'string', format: 'password' },
+                      redirectUri: { type: 'string', format: 'uri' },
+                    },
+                    required: ['username', 'password', 'redirectUri'],
+                  },
+                },
+              },
+            },
+            responses: {
+              '302': { description: 'Redirects to the provided URI with the session cookie set' },
+              '401': { description: 'Invalid credentials' },
+            },
+            security: [],
+          },
+        }
+      }
+    }
+
+    for (const expose of this.model.exposes.values()) {
+      const colPath = expose.getAbsoluteCollectionPath()
+      const resPath = expose.getAbsoluteResourcePath()
+
+      const domainEntity = this.model.domain?.findEntity(expose.entity.key)
+      let schemaRef: ReferenceObject | undefined = undefined
+      if (domainEntity) {
+        schemaRef = schemaGen.generateRootRef(domainEntity)
+      }
+
+      const responseContent = schemaRef ? { content: { 'application/json': { schema: schemaRef } } } : {}
+      const responseListContent = schemaRef
+        ? { content: { 'application/json': { schema: { type: 'array' as const, items: schemaRef } } } }
+        : {}
+      const requestContent: RequestBodyObject | undefined = schemaRef
+        ? {
+            required: true,
+            content: { 'application/json': { schema: schemaRef } as MediaTypeObject },
+          }
+        : undefined
+
+      if (expose.hasCollection && colPath) {
+        const pathItem: PathItemObject = paths[colPath] || {}
+        paths[colPath] = pathItem
+
+        const listAction = expose.actions.find((a) => a.kind === 'list')
+        const createAction = expose.actions.find((a) => a.kind === 'create')
+
+        if (listAction) {
+          const op: OperationObject = {
+            operationId: `list_${expose.key}`,
+            responses: { '200': { description: 'Success', ...responseListContent } },
+          }
+          this.applyActionSecurity(listAction, op)
+          pathItem.get = op
+        }
+
+        if (createAction) {
+          const op: OperationObject = {
+            operationId: `create_${expose.key}`,
+            requestBody: requestContent,
+            responses: { '201': { description: 'Created', ...responseContent } },
+          }
+          this.applyActionSecurity(createAction, op)
+          pathItem.post = op
+        }
+      }
+
+      if (resPath) {
+        const pathItem: PathItemObject = paths[resPath] || {}
+        paths[resPath] = pathItem
+
+        const readAction = expose.actions.find((a) => a.kind === 'read')
+        const updateAction = expose.actions.find((a) => a.kind === 'update')
+        const deleteAction = expose.actions.find((a) => a.kind === 'delete')
+
+        const parameters = this.extractPathParameters(resPath)
+
+        if (readAction) {
+          const op: OperationObject = {
+            operationId: `read_${expose.key}`,
+            parameters,
+            responses: { '200': { description: 'Success', ...responseContent } },
+          }
+          this.applyActionSecurity(readAction, op)
+          pathItem.get = op
+        }
+
+        if (updateAction) {
+          const op: OperationObject = {
+            operationId: `update_${expose.key}`,
+            parameters,
+            requestBody: requestContent,
+            responses: { '200': { description: 'Updated', ...responseContent } },
+          }
+          this.applyActionSecurity(updateAction, op)
+          pathItem.put = op
+        }
+
+        if (deleteAction) {
+          const op: OperationObject = {
+            operationId: `delete_${expose.key}`,
+            parameters,
+            responses: { '204': { description: 'Deleted' } },
+          }
+          this.applyActionSecurity(deleteAction, op)
+          pathItem.delete = op
+        }
+      }
+    }
+
+    return paths
+  }
+
+  private extractPathParameters(path: string): (ReferenceObject | ParameterObject)[] {
+    const params: (ReferenceObject | ParameterObject)[] = []
+    const regex = /\{([^}]+)\}/g
+    let match: RegExpExecArray | null
+    while ((match = regex.exec(path)) !== null) {
+      params.push({
+        name: match[1],
+        in: 'path',
+        required: true,
+        schema: { type: 'string' },
+      })
+    }
+    return params
+  }
+
+  private applyActionSecurity(action: Action, operation: OperationObject): void {
+    const rules = action.accessRule
+
+    // Check if anonymous access is explicitly allowed via an AllowPublic rule
+    const isPublic = rules.some((r) => r.type === 'allowPublic')
+    if (isPublic) {
+      operation.security = []
+      return
+    }
+
+    if (rules.length > 0) {
+      // It's restricted. Define operational security requirements.
+      const items: SecurityRequirementObject[] = []
+      if (this.model.session?.jwt?.enabled) items.push({ BearerAuth: [] })
+      if (this.model.session?.cookie?.enabled) items.push({ CookieAuth: [] })
+
+      if (items.length > 0) {
+        operation.security = items
+      }
+    }
+
+    // Extract any matching roles specific to the RBAC capabilities
+    const roleRules = rules.filter((r) => r.type === 'matchUserRole') as MatchUserRoleAccessRule[]
+    const roles = roleRules.flatMap((r) => r.role || [])
+
+    if (roles.length > 0) {
+      const uniqueRoles = Array.from(new Set(roles))
+
+      // Inject natively as vendor extension for processing tooling
+      // ;(operation as any)['x-roles'] = uniqueRoles
+
+      // Append strictly to the markdown description so developers always see the RBAC bounds
+      const rolesDesc = `**Required Roles:** ${uniqueRoles.join(', ')}`
+      operation.description = operation.description ? `${operation.description}\n\n${rolesDesc}` : rolesDesc
+    }
+  }
+}

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

@@ -0,0 +1,255 @@
+import type { ReferenceObject, SchemaObject } from './types.js'
+import { AssociationWebBindings, PropertyWebBindings } from '../../Bindings.js'
+import type { DataDomain } from '../../DataDomain.js'
+import type { DomainEntity } from '../../DomainEntity.js'
+import type { DomainProperty } from '../../DomainProperty.js'
+import { SemanticType } from '../../Semantics.js'
+
+export class OasSchemaGenerator {
+  private memorySchemas: Record<string, SchemaObject> = {}
+  private memoryNames: Record<string, string> = {}
+
+  constructor(private domain: DataDomain) {}
+
+  /**
+   * 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 = {
+      type: 'object',
+      properties: {},
+      required: [],
+    }
+    this.memorySchemas[entity.key] = schema
+    const schemaKey = this.generateSchemaKey(entity)
+    this.memoryNames[entity.key] = schemaKey
+
+    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
+    }
+  }
+
+  private mapPropertyBase(prop: DomainProperty, webBindings?: PropertyWebBindings): SchemaObject | ReferenceObject {
+    const base: SchemaObject = {}
+
+    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) {
+        base.examples = [...prop.schema.examples]
+      }
+    }
+
+    if (prop.info && prop.info.description) {
+      base.description = prop.info.description
+    }
+
+    if (prop.hasSemantic(SemanticType.Password)) {
+      base.format = 'password'
+    }
+
+    if (webBindings?.xml) {
+      base.xml = { ...webBindings.xml }
+    }
+
+    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
+  }
+}