feat: support for reusable pathItems definitions in components for OAS 3.1

package.json

@@ -31,8 +31,8 @@
     "update-lock-file": "update-lock-file @netcracker"
   },
   "dependencies": {
-    "@netcracker/qubership-apihub-api-diff": "2.2.0",
-    "@netcracker/qubership-apihub-api-unifier": "2.3.0",
+    "@netcracker/qubership-apihub-api-diff": "dev",
+    "@netcracker/qubership-apihub-api-unifier": "dev",
     "@netcracker/qubership-apihub-graphapi": "1.0.8",
     "@netcracker/qubership-apihub-json-crawl": "1.0.4",
     "adm-zip": "0.5.10",

src/apitypes/rest/rest.operation.ts

@@ -36,6 +36,7 @@ import {
   isOperationDeprecated,
   normalizePath,
   rawToApiKind,
+  resolveRefAndMap,
   setValueByPath,
   takeIf,
   takeIfDefined,
@@ -49,6 +50,7 @@ import {
   JSON_SCHEMA_PROPERTY_DEPRECATED,
   matchPaths,
   OPEN_API_PROPERTY_COMPONENTS,
+  OPEN_API_PROPERTY_PATH_ITEMS,
   OPEN_API_PROPERTY_PATHS,
   OPEN_API_PROPERTY_SCHEMAS,
   parseRef,
@@ -212,21 +214,28 @@ export const calculateSpecRefs = (sourceDocument: unknown, normalizedSpec: unkno
       return
     }
     const componentName = matchResult.grepValues[grepKey].toString()
-    const component = getKeyValue(sourceDocument, ...matchResult.path)
-    if (!component) {
+    let sourceComponents = getKeyValue(sourceDocument, ...matchResult.path)
+    if (!sourceComponents || typeof sourceComponents !== 'object') {
       return
     }
+
+    if (typeof sourceComponents === 'object') {
+      const allowedOps = getAllowedHttpOps(resultSpec, matchResult.path)
+      if (allowedOps.length > 0 && isComponentsPathItemRef(matchResult.path)) {
+        sourceComponents = filterPathItemOperations(sourceComponents, allowedOps)
+      }
+    }
     if (models && !models[componentName] && isComponentsSchemaRef(matchResult.path)) {
-      let componentHash = componentsHashMap?.get(componentName)
-      if (componentHash) {
-        models[componentName] = componentHash
+      const existingHash = componentsHashMap?.get(componentName)
+      if (existingHash) {
+        models[componentName] = existingHash
       } else {
-        componentHash = calculateObjectHash(component)
-        componentsHashMap?.set(componentName, componentHash)
-        models[componentName] = componentHash
+        const componentHashCalculated = calculateObjectHash(sourceComponents as object)
+        componentsHashMap?.set(componentName, componentHashCalculated)
+        models[componentName] = componentHashCalculated
       }
     }
-    setValueByPath(resultSpec, matchResult.path, component)
+    setValueByPath(resultSpec, matchResult.path, sourceComponents)
   })
 }
 
@@ -236,6 +245,38 @@ export const isComponentsSchemaRef = (path: JsonPath): boolean => {
     [[OPEN_API_PROPERTY_COMPONENTS, OPEN_API_PROPERTY_SCHEMAS, PREDICATE_UNCLOSED_END]],
   )
 }
+export const isComponentsPathItemRef = (path: JsonPath): boolean => {
+  return !!matchPaths(
+    [path],
+    [[OPEN_API_PROPERTY_COMPONENTS, OPEN_API_PROPERTY_PATH_ITEMS, PREDICATE_UNCLOSED_END]],
+  )
+}
+
+export const filterPathItemOperations = (
+  source: unknown,
+  allowedMethods: string[],
+): unknown => {
+  const httpMethods = new Set<string>(Object.values(OpenAPIV3.HttpMethods) as string[])
+  const filteredSource: Record<string, unknown> = { ...(source as Record<string, unknown>) }
+
+  for (const key of Object.keys(filteredSource)) {
+    if (httpMethods.has(key) && !allowedMethods.includes(key)) {
+      delete filteredSource[key]
+    }
+  }
+
+  return filteredSource
+}
+
+export const getAllowedHttpOps = (resultSpec: unknown, jsonPath: JsonPath): string[] => {
+  const resultComponents = getKeyValue(resultSpec, ...jsonPath) as unknown
+  if (typeof resultComponents !== 'object' || resultComponents === null) {
+    return []
+  }
+  const httpMethods = new Set<string>(Object.values(OpenAPIV3.HttpMethods) as string[])
+  return Object.keys(resultComponents as Record<string, unknown>).filter(key => httpMethods.has(key))
+}
+
 const isOperationPaths = (paths: JsonPath[]): boolean => {
   return !!matchPaths(
     paths,
@@ -255,21 +296,50 @@ const createSingleOperationSpec = (
   security?: OpenAPIV3.SecurityRequirementObject[],
   securitySchemes?: { [p: string]: OpenAPIV3.ReferenceObject | OpenAPIV3.SecuritySchemeObject },
 ): TYPE.RestOperationData => {
-  const pathData = document.paths[path] as OpenAPIV3.PathItemObject
+  const pathData = document.paths[path] as OpenAPIV3.PathItemObject | undefined
+  if (!pathData) {
+    throw new Error(`Path "${path}" not found in the document`)
+  }
 
-  return {
+  const baseSpec = {
     openapi: openapi ?? '3.0.0',
     ...takeIfDefined({ servers }),
     ...takeIfDefined({ security }), // TODO: remove duplicates in security
+    components: {
+      ...takeIfDefined({ securitySchemes }),
+    },
+  }
+
+  if (pathData.$ref) {
+    const cleanedDocument = resolveRefAndMap(
+      document,
+      pathData.$ref,
+      (pathItemObject: OpenAPIV3.PathItemObject) => ({
+        ...extractCommonPathItemProperties(pathItemObject),
+        [method]: { ...pathItemObject[method] },
+      }),
+    )
+
+    return {
+      ...baseSpec,
+      paths: {
+        [path]: pathData,
+      },
+      components: {
+        ...baseSpec.components,
+        ...cleanedDocument?.components ?? {},
+      },
+    }
+  }
+
+  return {
+    ...baseSpec,
     paths: {
       [path]: {
         ...extractCommonPathItemProperties(pathData),
         [method]: { ...pathData[method] },
       },
     },
-    components: {
-      ...takeIfDefined({ securitySchemes }),
-    },
   }
 }
 
@@ -281,3 +351,4 @@ export const extractCommonPathItemProperties = (
   ...takeIfDefined({ servers: pathData?.servers }),
   ...takeIfDefined({ parameters: pathData?.parameters }),
 })
+

src/apitypes/rest/rest.operations.ts

@@ -61,7 +61,7 @@ export const buildRestOperations: OperationsBuilder<OpenAPIV3.Document> = async
     debugCtx,
   )
 
-  const { paths, servers } = document.data
+  const { paths, servers } = effectiveDocument
 
   const operations: TYPE.VersionRestOperation[] = []
   if (!paths) { return [] }

src/strategies/document-group.strategy.ts

@@ -28,6 +28,8 @@ import { REST_API_TYPE } from '../apitypes'
 import {
   EXPORT_FORMAT_TO_FILE_FORMAT,
   fromBase64,
+  getParentValueByRef,
+  resolveRefAndMap,
   removeFirstSlash,
   slugify,
   takeIfDefined,
@@ -43,19 +45,12 @@ import { calculateSpecRefs, extractCommonPathItemProperties } from '../apitypes/
 function getTransformedDocument(document: ResolvedGroupDocument, format: FileFormat, packages: ResolvedReferenceMap): VersionRestDocument {
   const versionDocument = toVersionDocument(document, format)
 
-  const source = extractDocumentData(versionDocument)
+  const sourceDocument = extractDocumentData(versionDocument)
   versionDocument.data = transformDocumentData(versionDocument)
-  const normalizedDocument = normalize(
-    versionDocument.data,
-    {
-      ...NORMALIZE_OPTIONS,
-      inlineRefsFlag: INLINE_REFS_FLAG,
-      source,
-    },
-  ) as OpenAPIV3.Document
+  const normalizedDocument = normalizeOpenApi(versionDocument.data, sourceDocument)
   versionDocument.publish = true
 
-  calculateSpecRefs(source, normalizedDocument, versionDocument.data)
+  calculateSpecRefs(sourceDocument, normalizedDocument, versionDocument.data)
 
   // dashboard case
   if (document.packageRef) {
@@ -103,7 +98,7 @@ export class DocumentGroupStrategy implements BuilderStrategy {
   }
 }
 
-function parseBase64String(value: string): object {
+function parseBase64String(value: string): unknown {
   return JSON.parse(fromBase64(value))
 }
 
@@ -116,48 +111,136 @@ function extractDocumentData(versionDocument: VersionDocument): OpenAPIV3.Docume
 }
 
 function transformDocumentData(versionDocument: VersionDocument): OpenAPIV3.Document {
+  const sourceDocument = extractDocumentData(versionDocument)
+  const normalizedDocument = normalizeOpenApi(sourceDocument)
+  const { paths: sourcePaths, components: sourceComponents, ...restOfSource } = sourceDocument
+  const { paths: normalizedPaths } = normalizedDocument
 
-  const documentData = extractDocumentData(versionDocument)
-  const { paths, components, ...rest } = documentData
-  const result: OpenAPIV3.Document = {
-    ...rest,
+  const resultDocument: OpenAPIV3.Document = {
+    ...restOfSource,
     paths: {},
   }
 
-  for (const path of Object.keys(paths)) {
-    const pathData = paths[path]
-    if (typeof pathData !== 'object' || !pathData) {
+  for (const path of Object.keys(normalizedPaths)) {
+    const sourcePathItem = sourcePaths[path]
+    const normalizedPathItem = normalizedPaths[path]
+
+    if (!isNonNullObject(sourcePathItem) || !isNonNullObject(normalizedPathItem)) {
       continue
     }
-    const commonPathItemProperties = extractCommonPathItemProperties(pathData)
 
-    for (const method of Object.keys(pathData)) {
-      const inferredMethod = method as OpenAPIV3.HttpMethods
+    const commonProps = extractCommonPathItemProperties(sourcePathItem)
 
-      // check if field is a valid openapi http method defined in OpenAPIV3.HttpMethods
-      if (!Object.values(OpenAPIV3.HttpMethods).includes(inferredMethod)) {
-        continue
-      }
+    for (const method of Object.keys(normalizedPathItem)) {
+      const httpMethod = method as OpenAPIV3.HttpMethods
+      if (!isValidHttpMethod(httpMethod)) continue
 
-      const methodData = pathData[inferredMethod]
-      const basePath = getOperationBasePath(methodData?.servers || pathData?.servers || documentData?.servers || [])
-      const operationPath = basePath + path
+      const methodData = normalizedPathItem[httpMethod]
+      const basePath = getOperationBasePath(
+        methodData?.servers ||
+        sourcePathItem?.servers ||
+        sourceDocument?.servers ||
+        [],
+      )
 
+      const operationPath = basePath + path
       const operationId = slugify(`${removeFirstSlash(operationPath)}-${method}`)
 
-      if (versionDocument.operationIds.includes(operationId)) {
-        const pathData = documentData.paths[path]!
-        result.paths[path] = {
-          ...result.paths[path],
-          ...commonPathItemProperties,
-          [inferredMethod]: { ...pathData[inferredMethod] },
-        }
-        result.components = {
-          ...takeIfDefined({ securitySchemes: components?.securitySchemes }),
+      if (!versionDocument.operationIds.includes(operationId)) {
+        continue
+      }
+
+      const pathData = sourceDocument.paths[path]!
+      if (sourcePathItem?.$ref) {
+        handleRefPathItem(
+          resultDocument,
+          sourceDocument,
+          path,
+          pathData,
+          httpMethod,
+        )
+      } else {
+        handleInlinePathItem(
+          resultDocument,
+          path,
+          pathData,
+          httpMethod,
+          commonProps,
+        )
+      }
+
+      if (sourceComponents?.securitySchemes) {
+        resultDocument.components = {
+          ...resultDocument.components,
+          securitySchemes: sourceComponents.securitySchemes,
         }
       }
     }
   }
 
-  return result
+  return resultDocument
+}
+
+function handleRefPathItem(
+  resultDoc: OpenAPIV3.Document,
+  sourceDoc: OpenAPIV3.Document,
+  path: string,
+  pathData: OpenAPIV3.PathItemObject | OpenAPIV3.ReferenceObject,
+  method: OpenAPIV3.HttpMethods,
+): void {
+  const targetFromResultDoc = getParentValueByRef(resultDoc, (pathData as any).$ref ?? '')
+
+  const target = resolveRefAndMap(
+    sourceDoc,
+    (pathData as any).$ref ?? '',
+    (pathItemObject: OpenAPIV3.PathItemObject) => ({
+      ...targetFromResultDoc,
+      ...extractCommonPathItemProperties(pathItemObject),
+      [method]: { ...pathItemObject[method] },
+    }),
+  )
+
+  resultDoc.paths[path] = pathData
+
+  if (target.components) {
+    resultDoc.components = {
+      ...resultDoc.components,
+      ...target.components,
+    }
+  }
+}
+
+function handleInlinePathItem(
+  resultDoc: OpenAPIV3.Document,
+  path: string,
+  pathData: OpenAPIV3.PathItemObject,
+  method: OpenAPIV3.HttpMethods,
+  commonProps: Partial<OpenAPIV3.PathItemObject>,
+): void {
+  const existingPath = resultDoc.paths[path]
+
+  resultDoc.paths[path] = {
+    ...existingPath,
+    ...commonProps,
+    [method]: { ...pathData[method] },
+  }
+}
+
+function normalizeOpenApi(document: OpenAPIV3.Document, source?: OpenAPIV3.Document): OpenAPIV3.Document {
+  return normalize(
+    document,
+    {
+      ...NORMALIZE_OPTIONS,
+      inlineRefsFlag: INLINE_REFS_FLAG,
+      ...(source ? { source } : {}),
+    },
+  ) as OpenAPIV3.Document
+}
+
+function isValidHttpMethod(method: string): method is OpenAPIV3.HttpMethods {
+  return (Object.values(OpenAPIV3.HttpMethods) as string[]).includes(method)
+}
+
+function isNonNullObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null
 }