feat: POC ref pathItems support

Author: makeev-pavel

src/apitypes/rest/rest.operation.ts

@@ -19,38 +19,40 @@ import { OpenAPIV3 } from 'openapi-types'
 import { REST_API_TYPE, REST_KIND_KEY } from './rest.consts'
 import { operationRules } from './rest.rules'
 import type * as TYPE from './rest.types'
-import type {
+import {
   BuildConfig,
   CrawlRule,
   DeprecateItem,
   NotificationMessage,
   OperationCrawlState,
+  OperationId,
   SearchScopes,
 } from '../../types'
 import {
   buildSearchScope,
   capitalize,
   getKeyValue,
   getSplittedVersionKey,
-  getValueByRefAndUpdate,
   isDeprecatedOperationItem,
+  isObject,
   isOperationDeprecated,
   normalizePath,
   rawToApiKind,
+  removeFirstSlash,
   setValueByPath,
+  slugify,
   takeIf,
   takeIfDefined,
 } from '../../utils'
 import { API_KIND, INLINE_REFS_FLAG, ORIGINS_SYMBOL, VERSION_STATUS } from '../../consts'
-import { getCustomTags, resolveApiAudience } from './rest.utils'
+import { getCustomTags, getOperationBasePath, resolveApiAudience } from './rest.utils'
 import { DebugPerformanceContext, syncDebugPerformance } from '../../utils/logs'
 import {
   calculateDeprecatedItems,
   grepValue,
   JSON_SCHEMA_PROPERTY_DEPRECATED,
   matchPaths,
   OPEN_API_PROPERTY_COMPONENTS,
-  OPEN_API_PROPERTY_PATH_ITEMS,
   OPEN_API_PROPERTY_PATHS,
   OPEN_API_PROPERTY_SCHEMAS,
   parseRef,
@@ -61,6 +63,7 @@ import {
 } from '@netcracker/qubership-apihub-api-unifier'
 import { calculateObjectHash } from '../../utils/hashes'
 import { calculateTolerantHash } from '../../components/deprecated'
+import { getValueByPath } from '../../utils/path'
 
 export const buildRestOperation = (
   operationId: string,
@@ -145,7 +148,8 @@ export const buildRestOperation = (
       security,
       components?.securitySchemes,
     )
-    calculateSpecRefs(document.data, refsOnlySingleOperationSpec, specWithSingleOperation, models, componentsHashMap)
+    calculateSpecRefs(document.data, refsOnlySingleOperationSpec, specWithSingleOperation, [operationId], models, componentsHashMap)
+    createSinglePathItemOperationSpec(specWithSingleOperation as OpenAPIV3.Document, refsOnlySingleOperationSpec as OpenAPIV3.Document, [operationId])
     const dataHash = calculateObjectHash(specWithSingleOperation)
     return [specWithSingleOperation, dataHash]
   }, debugCtx)
@@ -182,7 +186,7 @@ export const buildRestOperation = (
   }
 }
 
-export const calculateSpecRefs = (sourceDocument: unknown, normalizedSpec: unknown, resultSpec: unknown, models?: Record<string, string>, componentsHashMap?: Map<string, string>): void => {
+export const calculateSpecRefs = (sourceDocument: unknown, normalizedSpec: unknown, resultSpec: unknown, operations: OperationId[], models?: Record<string, string>, componentsHashMap?: Map<string, string>): void => {
   const handledObjects = new Set<unknown>()
   const inlineRefs = new Set<string>()
   syncCrawl(
@@ -214,67 +218,70 @@ export const calculateSpecRefs = (sourceDocument: unknown, normalizedSpec: unkno
       return
     }
     const componentName = matchResult.grepValues[grepKey].toString()
-    let sourceComponents = getKeyValue(sourceDocument, ...matchResult.path)
-    if (!sourceComponents || typeof sourceComponents !== 'object') {
+    let component: any = getKeyValue(sourceDocument, ...matchResult.path)
+    if (!component) {
       return
     }
-
-    if (typeof sourceComponents === 'object') {
-      const allowedOps = getAllowedHttpOps(resultSpec, matchResult.path)
-      if (allowedOps.length > 0 && isComponentsPathItemRef(matchResult.path)) {
-        sourceComponents = filterPathItemOperations(sourceComponents, allowedOps)
-      }
+    if (isObject(component)) {
+      component = { ...component }
     }
     if (models && !models[componentName] && isComponentsSchemaRef(matchResult.path)) {
-      const existingHash = componentsHashMap?.get(componentName)
-      if (existingHash) {
-        models[componentName] = existingHash
+      let componentHash = componentsHashMap?.get(componentName)
+      if (componentHash) {
+        models[componentName] = componentHash
       } else {
-        const componentHashCalculated = calculateObjectHash(sourceComponents as object)
-        componentsHashMap?.set(componentName, componentHashCalculated)
-        models[componentName] = componentHashCalculated
+        componentHash = calculateObjectHash(component)
+        componentsHashMap?.set(componentName, componentHash)
+        models[componentName] = componentHash
       }
     }
-    setValueByPath(resultSpec, matchResult.path, sourceComponents)
+
+    setValueByPath(resultSpec, matchResult.path, component)
   })
 }
 
-export const isComponentsSchemaRef = (path: JsonPath): boolean => {
-  return !!matchPaths(
-    [path],
-    [[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 function createSinglePathItemOperationSpec(sourceDocument: OpenAPIV3.Document, normalizedDocument: OpenAPIV3.Document, operations: OperationId[]): void {
+  const { paths } = normalizedDocument
 
-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 path of Object.keys(paths)) {
+    const sourcePathItem = paths[path]
 
-  for (const key of Object.keys(filteredSource)) {
-    if (httpMethods.has(key) && !allowedMethods.includes(key)) {
-      delete filteredSource[key]
+    const refs = (sourcePathItem as any)[INLINE_REFS_FLAG]
+    if (!isNonNullObject(sourcePathItem) || !refs || refs.length === 0) {
+      continue
+    }
+    const richReference = parseRef(refs[0])
+    const valueByPath = getValueByPath(sourceDocument, richReference.jsonPath)
+    for (const method of Object.keys(valueByPath)) {
+      const httpMethod = method as OpenAPIV3.HttpMethods
+      if (!isValidHttpMethod(httpMethod)) continue
+
+      const methodData = sourcePathItem[httpMethod]
+      const basePath = getOperationBasePath(
+        methodData?.servers ||
+        sourcePathItem?.servers ||
+        [],
+      )
+
+      const operationPath = basePath + path
+      const operationId = slugify(`${removeFirstSlash(operationPath)}-${method}`)
+
+      if (!operations.includes(operationId)) {
+        delete valueByPath[method]
+      }
     }
   }
+}
 
-  return filteredSource
+function isNonNullObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null
 }
 
-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))
+export const isComponentsSchemaRef = (path: JsonPath): boolean => {
+  return !!matchPaths(
+    [path],
+    [[OPEN_API_PROPERTY_COMPONENTS, OPEN_API_PROPERTY_SCHEMAS, PREDICATE_UNCLOSED_END]],
+  )
 }
 
 const isOperationPaths = (paths: JsonPath[]): boolean => {
@@ -296,51 +303,27 @@ const createSingleOperationSpec = (
   security?: OpenAPIV3.SecurityRequirementObject[],
   securitySchemes?: { [p: string]: OpenAPIV3.ReferenceObject | OpenAPIV3.SecuritySchemeObject },
 ): TYPE.RestOperationData => {
-  const pathData = document.paths[path] as OpenAPIV3.PathItemObject | undefined
-  if (!pathData) {
-    throw new Error(`Path "${path}" not found in the document`)
-  }
+  const pathData = document.paths[path] as OpenAPIV3.PathItemObject
 
-  const baseSpec = {
+  const ref = pathData.$ref
+  const refFlag = (pathData as any)[INLINE_REFS_FLAG]
+  return {
     openapi: openapi ?? '3.0.0',
     ...takeIfDefined({ servers }),
     ...takeIfDefined({ security }), // TODO: remove duplicates in security
+    paths: {
+      [path]: ref
+        ? pathData
+        : {
+          ...extractCommonPathItemProperties(pathData),
+          [method]: { ...pathData[method] },
+          ...(refFlag ? { [INLINE_REFS_FLAG]: refFlag } : {}),
+        },
+    },
     components: {
       ...takeIfDefined({ securitySchemes }),
     },
   }
-
-  const ref = pathData.$ref
-  if (ref) {
-    const cleanedDocument = getValueByRefAndUpdate(
-      ref,
-      document,
-      (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] },
-      },
-    },
-  }
 }
 
 export const extractCommonPathItemProperties = (
@@ -352,3 +335,6 @@ export const extractCommonPathItemProperties = (
   ...takeIfDefined({ parameters: pathData?.parameters }),
 })
 
+function isValidHttpMethod(method: string): method is OpenAPIV3.HttpMethods {
+  return (Object.values(OpenAPIV3.HttpMethods) as string[]).includes(method)
+}

src/strategies/document-group.strategy.ts

@@ -28,28 +28,32 @@ import { REST_API_TYPE } from '../apitypes'
 import {
   EXPORT_FORMAT_TO_FILE_FORMAT,
   fromBase64,
-  getParentValueByRef,
-  getValueByRefAndUpdate,
   removeFirstSlash,
   slugify,
+  takeIfDefined,
   toVersionDocument,
 } from '../utils'
 import { OpenAPIV3 } from 'openapi-types'
 import { getOperationBasePath } from '../apitypes/rest/rest.utils'
 import { VersionRestDocument } from '../apitypes/rest/rest.types'
 import { FILE_FORMAT_JSON, INLINE_REFS_FLAG, NORMALIZE_OPTIONS } from '../consts'
 import { normalize } from '@netcracker/qubership-apihub-api-unifier'
-import { calculateSpecRefs, extractCommonPathItemProperties } from '../apitypes/rest/rest.operation'
+import {
+  calculateSpecRefs,
+  createSinglePathItemOperationSpec,
+  extractCommonPathItemProperties,
+} from '../apitypes/rest/rest.operation'
 
 function getTransformedDocument(document: ResolvedGroupDocument, format: FileFormat, packages: ResolvedReferenceMap): VersionRestDocument {
   const versionDocument = toVersionDocument(document, format)
 
   const sourceDocument = extractDocumentData(versionDocument)
   versionDocument.data = transformDocumentData(versionDocument)
   const normalizedDocument = normalizeOpenApi(versionDocument.data, sourceDocument)
+  createSinglePathItemOperationSpec(sourceDocument, normalizedDocument, versionDocument.operationIds)
   versionDocument.publish = true
 
-  calculateSpecRefs(sourceDocument, normalizedDocument, versionDocument.data)
+  calculateSpecRefs(sourceDocument, normalizedDocument, versionDocument.data, versionDocument.operationIds)
 
   // dashboard case
   if (document.packageRef) {
@@ -128,7 +132,7 @@ function transformDocumentData(versionDocument: VersionDocument): OpenAPIV3.Docu
       continue
     }
 
-    const commonProps = extractCommonPathItemProperties(sourcePathItem)
+    const commonPathItemProperties = extractCommonPathItemProperties(sourcePathItem)
 
     for (const method of Object.keys(normalizedPathItem)) {
       const httpMethod = method as OpenAPIV3.HttpMethods
@@ -149,29 +153,21 @@ function transformDocumentData(versionDocument: VersionDocument): OpenAPIV3.Docu
         continue
       }
 
-      const pathData = sourceDocument.paths[path]!
-      if (sourcePathItem?.$ref) {
-        handleRefPathItem(
-          resultDocument,
-          sourceDocument,
-          path,
-          pathData,
-          httpMethod,
-        )
-      } else {
-        handleInlinePathItem(
-          resultDocument,
-          path,
-          pathData,
-          httpMethod,
-          commonProps,
-        )
-      }
+      if (versionDocument.operationIds.includes(operationId)) {
+        const pathData = sourceDocument.paths[path]!
+        const ref = pathData.$ref ?? ''
+        if (ref) {
+          resultDocument.paths[path] = pathData
+        } else {
+          resultDocument.paths[path] = {
+            ...resultDocument.paths[path],
+            ...commonPathItemProperties,
+            [httpMethod]: { ...pathData[httpMethod] },
+          }
 
-      if (sourceComponents?.securitySchemes) {
+        }
         resultDocument.components = {
-          ...resultDocument.components,
-          securitySchemes: sourceComponents.securitySchemes,
+          ...takeIfDefined({ securitySchemes: sourceComponents?.securitySchemes }),
         }
       }
     }
@@ -180,48 +176,6 @@ function transformDocumentData(versionDocument: VersionDocument): OpenAPIV3.Docu
   return resultDocument
 }
 
-function handleRefPathItem(
-  resultDocument: OpenAPIV3.Document,
-  sourceDocument: OpenAPIV3.Document,
-  path: string,
-  pathData: OpenAPIV3.PathItemObject | OpenAPIV3.ReferenceObject,
-  method: OpenAPIV3.HttpMethods,
-): void {
-  const ref = pathData.$ref ?? ''
-  const operationsFormResult = getParentValueByRef(ref, resultDocument)
-
-  const cleanedDocument = getValueByRefAndUpdate(ref, sourceDocument, (pathItemObject: OpenAPIV3.PathItemObject) => ({
-    ...operationsFormResult,
-    ...extractCommonPathItemProperties(pathItemObject),
-    [method]: { ...pathItemObject[method] },
-  }))
-
-  resultDocument.paths[path] = pathData
-
-  if (cleanedDocument.components) {
-    resultDocument.components = {
-      ...resultDocument.components,
-      ...cleanedDocument.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,