feat: Support undocumented/deprecated namespace and routes (#86)

* Mark routes with isDeprecated and isUndocumented * Refactor how route status is updated into a separate fn * ci: Generate code * Update namspace status * Refactor updateRoutesStatus into updateRoutesStatus * Use for loops instead of forEach * ci: Generate code * Format * Avoid generic fn names, use simple map functions to set route/namespace deprecated/undocumented status * Improve var names * Add deprecated and undocumented endpoint to the fixture * ci: Generate code * Pass updated routes to addNamespaceStatusToRoute * ci: Generate code * Refactor addNamespaceStatusToRoute * Fix lint error * Tiny refactor --------- Co-authored-by: Seam Bot <devops@getseam.com>
seamapi · Sep 19, 2024 · bb84d86 · bb84d86
1 parent 9aa7b88
commit bb84d86
Show file tree

Hide file tree

Showing 9 changed files with 495 additions and 2 deletions.
diff --git a/src/lib/blueprint.ts b/src/lib/blueprint.ts
@@ -30,6 +30,8 @@ export interface Route {
   namespace: Namespace | null
   endpoints: Endpoint[]
   subroutes: Route[]
+  isUndocumented: boolean
+  isDeprecated: boolean
 }
 
 export interface Resource {
@@ -40,6 +42,8 @@ export interface Resource {
 
 export interface Namespace {
   path: string
+  isDeprecated: boolean
+  isUndocumented: boolean
 }
 
 export interface Endpoint {
@@ -307,7 +311,12 @@ const createRoutes = async (
     }
   }
 
-  return Array.from(routeMap.values())
+  const routes = Array.from(routeMap.values())
+
+  return routes
+    .map(addIsDeprecatedToRoute)
+    .map(addIsUndocumentedToRoute)
+    .map(addNamespaceStatusToRoute)
 }
 
 const getNamespace = (path: string, paths: OpenapiPaths): string | null => {
@@ -360,9 +369,51 @@ const createRoute = async (
   return {
     path: routePath,
     name,
-    namespace: namespace != null ? { path: namespace } : null,
+    namespace:
+      namespace != null
+        ? {
+            path: namespace,
+            isDeprecated: false,
+            isUndocumented: false,
+          }
+        : null,
     endpoints: await createEndpoints(path, pathItem, context),
     subroutes: [],
+    isUndocumented: false,
+    isDeprecated: false,
+  }
+}
+
+const addIsDeprecatedToRoute = (route: Route): Route => ({
+  ...route,
+  isDeprecated: route.endpoints.every((endpoint) => endpoint.isDeprecated),
+})
+
+const addIsUndocumentedToRoute = (route: Route): Route => ({
+  ...route,
+  isUndocumented: route.endpoints.every((endpoint) => endpoint.isUndocumented),
+})
+
+const addNamespaceStatusToRoute = (
+  route: Route,
+  _idx: number,
+  routes: Route[],
+): Route => {
+  if (route.namespace == null) return route
+
+  const namespaceRoutes = routes.filter(
+    (r) => r.namespace?.path === route.namespace?.path,
+  )
+  const isNamespaceDeprecated = namespaceRoutes.every((r) => r.isDeprecated)
+  const isNamespaceUndocumented = namespaceRoutes.every((r) => r.isUndocumented)
+
+  return {
+    ...route,
+    namespace: {
+      ...route.namespace,
+      isDeprecated: isNamespaceDeprecated,
+      isUndocumented: isNamespaceUndocumented,
+    },
   }
 }
 

diff --git a/test/fixtures/types/code-sample-definitions.ts b/test/fixtures/types/code-sample-definitions.ts
@@ -65,4 +65,15 @@ export default [
       },
     },
   },
+  {
+    title: 'Deprecated and undocumented endpoint',
+    description: 'This is a deprecated and undocumented endpoint',
+    request: {
+      path: '/deprecated/undocumented/endpoint',
+      parameters: {},
+    },
+    response: {
+      body: {},
+    },
+  },
 ]
diff --git a/test/fixtures/types/openapi.ts b/test/fixtures/types/openapi.ts
@@ -218,5 +218,32 @@ export default {
         'x-title': 'List planes',
       },
     },
+    '/deprecated/undocumented/endpoint': {
+      get: {
+        operationId: 'deprecatedUndocumentedEndpointGet',
+        deprecated: true,
+        responses: {
+          200: {
+            content: {
+              'application/json': {
+                schema: {
+                  properties: {
+                    ok: { type: 'boolean' },
+                  },
+                  required: ['ok'],
+                  type: 'object',
+                },
+              },
+            },
+            description: 'Deprecated and undocumented endpoint',
+          },
+        },
+        security: [],
+        summary: '/deprecated/undocumented/endpoint',
+        tags: ['/deprecated/undocumented'],
+        'x-undocumented': 'true',
+        'x-title': 'Deprecated and undocumented endpoint',
+      },
+    },
   },
 }
diff --git a/test/fixtures/types/route-specs.ts b/test/fixtures/types/route-specs.ts
@@ -23,5 +23,10 @@ export const routes = {
         planes: z.array(schemas.plane),
       }),
     },
+    '/deprecated/undocumented/endpoint': {
+      auth: 'none',
+      methods: ['GET'],
+      jsonResponse: z.object({}),
+    },
   },
 } as const
diff --git a/test/fixtures/types/route-types.ts b/test/fixtures/types/route-types.ts
@@ -53,6 +53,15 @@ export interface Routes {
       }
     }
   }
+  '/deprecated/undocumented/endpoint': {
+    route: '/deprecated/undocumented/endpoint'
+    method: 'GET'
+    queryParams: Record<string, unknown>
+    jsonBody: Record<string, unknown>
+    commonParams: Record<string, unknown>
+    formData: Record<string, unknown>
+    jsonResponse: Record<string, never>
+  }
 }
 
 export type RouteResponse<Path extends keyof Routes> =