feat: support for reusable pathItems definitions in components for OAS 3.1 (#35)

Author: makeev-pavel

src/apitypes/rest/index.ts

@@ -19,10 +19,10 @@ import { OpenAPIV3 } from 'openapi-types'
 import { buildRestDocument, createRestExportDocument, dumpRestDocument } from './rest.document'
 import { REST_API_TYPE, REST_DOCUMENT_TYPE } from './rest.consts'
 import { compareRestOperationsData } from './rest.changes'
-import { buildRestOperations, createNormalizedOperationId } from './rest.operations'
+import { buildRestOperations } from './rest.operations'
 import { parseRestFile } from './rest.parser'
-
 import { ApiBuilder } from '../../types'
+import { calculateNormalizedOperationId } from '../../utils'
 
 export * from './rest.consts'
 
@@ -34,6 +34,6 @@ export const restApiBuilder: ApiBuilder<OpenAPIV3.Document> = {
   buildOperations: buildRestOperations,
   dumpDocument: dumpRestDocument,
   compareOperationsData: compareRestOperationsData,
-  createNormalizedOperationId: createNormalizedOperationId,
+  createNormalizedOperationId: calculateNormalizedOperationId,
   createExportDocument: createRestExportDocument,
 }

src/apitypes/rest/rest.operation.ts

@@ -19,29 +19,35 @@ 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 { RestOperationData } from './rest.types'
+import {
   BuildConfig,
   CrawlRule,
   DeprecateItem,
   NotificationMessage,
   OperationCrawlState,
+  OperationId,
   SearchScopes,
 } from '../../types'
 import {
   buildSearchScope,
+  calculateOperationId,
   capitalize,
+  extractSymbolProperty,
   getKeyValue,
   getSplittedVersionKey,
+  getSymbolValueIfDefined,
   isDeprecatedOperationItem,
   isOperationDeprecated,
+  isValidHttpMethod,
   normalizePath,
   rawToApiKind,
   setValueByPath,
   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,
@@ -59,6 +65,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,
@@ -143,7 +150,7 @@ export const buildRestOperation = (
       security,
       components?.securitySchemes,
     )
-    calculateSpecRefs(document.data, refsOnlySingleOperationSpec, specWithSingleOperation, models, componentsHashMap)
+    calculateSpecRefs(document.data, refsOnlySingleOperationSpec, specWithSingleOperation, [operationId], models, componentsHashMap)
     const dataHash = calculateObjectHash(specWithSingleOperation)
     return [specWithSingleOperation, dataHash]
   }, debugCtx)
@@ -180,7 +187,14 @@ 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: TYPE.RestOperationData,
+  normalizedSpec: TYPE.RestOperationData,
+  resultSpec: TYPE.RestOperationData,
+  operations: OperationId[],
+  models?: Record<string, string>,
+  componentsHashMap?: Map<string, string>,
+): void => {
   const handledObjects = new Set<unknown>()
   const inlineRefs = new Set<string>()
   syncCrawl(
@@ -212,10 +226,11 @@ export const calculateSpecRefs = (sourceDocument: unknown, normalizedSpec: unkno
       return
     }
     const componentName = matchResult.grepValues[grepKey].toString()
-    const component = getKeyValue(sourceDocument, ...matchResult.path)
+    const component = getKeyValue(sourceDocument, ...matchResult.path) as Record<string, unknown>
     if (!component) {
       return
     }
+
     if (models && !models[componentName] && isComponentsSchemaRef(matchResult.path)) {
       let componentHash = componentsHashMap?.get(componentName)
       if (componentHash) {
@@ -226,8 +241,68 @@ export const calculateSpecRefs = (sourceDocument: unknown, normalizedSpec: unkno
         models[componentName] = componentHash
       }
     }
+
     setValueByPath(resultSpec, matchResult.path, component)
   })
+
+  if (operations?.length) {
+    reduceComponentPathItemsToOperations(resultSpec, normalizedSpec, operations)
+  }
+}
+
+function reduceComponentPathItemsToOperations(
+  resultSpec: RestOperationData,
+  normalizedDocument: RestOperationData,
+  operations: OperationId[],
+): void {
+  const { paths } = normalizedDocument
+
+  for (const path of Object.keys(paths)) {
+    const sourcePathItem = paths[path] as OpenAPIV3.PathItemObject
+    const pathItemComponentJsonPath = getPathItemComponentJsonPath(sourcePathItem)
+    if (!pathItemComponentJsonPath) {
+      continue
+    }
+
+    const pathItemComponent = getValueByPath(resultSpec, pathItemComponentJsonPath) as OpenAPIV3.PathItemObject
+
+    const operationIds: OpenAPIV3.HttpMethods[] = (Object.keys(pathItemComponent) as OpenAPIV3.HttpMethods[])
+      .filter((httpMethod) => isValidHttpMethod(httpMethod))
+      .filter(httpMethod => {
+        const methodData = sourcePathItem[httpMethod as OpenAPIV3.HttpMethods]
+        if (!methodData) return false
+        const basePath = getOperationBasePath(
+          methodData?.servers ||
+          sourcePathItem?.servers ||
+          [],
+        )
+        const operationId = calculateOperationId(basePath, httpMethod, path)
+        return operations.includes(operationId)
+      })
+
+    if (operationIds?.length) {
+      const pathItemObject = {
+        ...extractCommonPathItemProperties(pathItemComponent),
+        ...operationIds.reduce<OpenAPIV3.PathItemObject>((pathItemObject: OpenAPIV3.PathItemObject, operationId: OpenAPIV3.HttpMethods) => {
+          const operationData = pathItemComponent[operationId]
+          if (operationData) {
+            pathItemObject[operationId] = { ...operationData }
+          }
+          return pathItemObject
+        }, {}),
+      }
+      setValueByPath(resultSpec, pathItemComponentJsonPath, pathItemObject)
+    }
+  }
+}
+
+const getPathItemComponentJsonPath = (sourcePathItem: OpenAPIV3.PathItemObject): JsonPath | undefined => {
+  const refs = getSymbolValueIfDefined(sourcePathItem, INLINE_REFS_FLAG) as string[] | undefined
+  if (!refs || refs.length === 0) {
+    return undefined
+  }
+
+  return parseRef(refs[0])?.jsonPath
 }
 
 export const isComponentsSchemaRef = (path: JsonPath): boolean => {
@@ -236,6 +311,7 @@ export const isComponentsSchemaRef = (path: JsonPath): boolean => {
     [[OPEN_API_PROPERTY_COMPONENTS, OPEN_API_PROPERTY_SCHEMAS, PREDICATE_UNCLOSED_END]],
   )
 }
+
 const isOperationPaths = (paths: JsonPath[]): boolean => {
   return !!matchPaths(
     paths,
@@ -257,15 +333,19 @@ const createSingleOperationSpec = (
 ): TYPE.RestOperationData => {
   const pathData = document.paths[path] as OpenAPIV3.PathItemObject
 
+  const isRefPathData = !!pathData.$ref
   return {
     openapi: openapi ?? '3.0.0',
     ...takeIfDefined({ servers }),
     ...takeIfDefined({ security }), // TODO: remove duplicates in security
     paths: {
-      [path]: {
-        ...extractCommonPathItemProperties(pathData),
-        [method]: { ...pathData[method] },
-      },
+      [path]: isRefPathData
+        ? pathData
+        : {
+          ...extractCommonPathItemProperties(pathData),
+          [method]: { ...pathData[method] },
+          ...extractSymbolProperty(pathData, INLINE_REFS_FLAG),
+        },
     },
     components: {
       ...takeIfDefined({ securitySchemes }),

src/apitypes/rest/rest.operations.ts

@@ -17,14 +17,8 @@
 import { OpenAPIV3 } from 'openapi-types'
 
 import { buildRestOperation } from './rest.operation'
-import { OperationIdNormalizer, OperationsBuilder } from '../../types'
-import {
-  createBundlingErrorHandler,
-  IGNORE_PATH_PARAM_UNIFIED_PLACEHOLDER,
-  removeComponents,
-  removeFirstSlash,
-  slugify,
-} from '../../utils'
+import { OperationsBuilder } from '../../types'
+import { calculateOperationId, createBundlingErrorHandler, removeComponents } from '../../utils'
 import { getOperationBasePath } from './rest.utils'
 import type * as TYPE from './rest.types'
 import { HASH_FLAG, INLINE_REFS_FLAG, MESSAGE_SEVERITY, NORMALIZE_OPTIONS, ORIGINS_SYMBOL } from '../../consts'
@@ -61,7 +55,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 [] }
@@ -77,9 +71,8 @@ export const buildRestOperations: OperationsBuilder<OpenAPIV3.Document> = async
       await asyncFunction(() => {
         const methodData = pathData[key as OpenAPIV3.HttpMethods]
         const basePath = getOperationBasePath(methodData?.servers || pathData?.servers || servers || [])
-        const operationPath = basePath + path
 
-        const operationId = slugify(`${removeFirstSlash(operationPath)}-${key}`)
+        const operationId = calculateOperationId(basePath, key, path)
 
         if (ctx.operationResolver(operationId)) {
           ctx.notifications.push({
@@ -112,8 +105,3 @@ export const buildRestOperations: OperationsBuilder<OpenAPIV3.Document> = async
   }
   return operations
 }
-
-export const createNormalizedOperationId: OperationIdNormalizer = (operation) => {
-  const { metadata: { path, method } } = operation
-  return slugify(`${path}-${method}`, [], IGNORE_PATH_PARAM_UNIFIED_PLACEHOLDER)
-}

src/consts.ts

@@ -27,6 +27,7 @@ import {
   VALIDATION_RULES_SEVERITY_LEVEL_WARNING,
   ValidationRulesSeverity,
 } from './types'
+import { OpenAPIV3 } from 'openapi-types'
 
 export const DEFAULT_BATCH_SIZE = 32
 
@@ -169,3 +170,4 @@ export const EMPTY_CHANGE_SUMMARY_DTO = {
 }
 
 export const CUSTOM_PARAMETER_API_AUDIENCE = 'x-api-audience'
+export const HTTP_METHODS_SET = new Set(Object.values(OpenAPIV3.HttpMethods) as string[])