From 046e04a7cf4076ff30873dac6202bde98f3db35b Mon Sep 17 00:00:00 2001
From: Aramis Sennyey <sennyeya@amazon.com>
Date: Tue, 10 Jan 2023 13:07:12 -0500
Subject: [PATCH 01/61] Translated all endpoints to the new format, seeking
 feedback.

Signed-off-by: Aramis Sennyey <sennyeya@amazon.com>
---
 plugins/catalog-backend/package.json          |   2 +
 .../src/service/createRouter.ts               | 301 +++++++++---------
 yarn.lock                                     | 187 ++++++++++-
 3 files changed, 331 insertions(+), 159 deletions(-)

diff --git a/plugins/catalog-backend/package.json b/plugins/catalog-backend/package.json
index db9e1845fe..65a3232e69 100644
--- a/plugins/catalog-backend/package.json
+++ b/plugins/catalog-backend/package.json
@@ -65,11 +65,13 @@
     "codeowners-utils": "^1.0.2",
     "core-js": "^3.6.5",
     "express": "^4.17.1",
+    "express-openapi": "^12.1.0",
     "express-promise-router": "^4.1.0",
     "fast-json-stable-stringify": "^2.1.0",
     "fs-extra": "10.1.0",
     "git-url-parse": "^13.0.0",
     "glob": "^7.1.6",
+    "js-yaml": "^4.1.0",
     "knex": "^2.0.0",
     "lodash": "^4.17.21",
     "luxon": "^3.0.0",
diff --git a/plugins/catalog-backend/src/service/createRouter.ts b/plugins/catalog-backend/src/service/createRouter.ts
index 849096c601..6b733a0a9a 100644
--- a/plugins/catalog-backend/src/service/createRouter.ts
+++ b/plugins/catalog-backend/src/service/createRouter.ts
@@ -23,7 +23,7 @@ import {
   stringifyEntityRef,
 } from '@backstage/catalog-model';
 import { Config } from '@backstage/config';
-import { NotFoundError, serializeError } from '@backstage/errors';
+import { InputError, NotFoundError, serializeError } from '@backstage/errors';
 import express from 'express';
 import Router from 'express-promise-router';
 import { Logger } from 'winston';
@@ -50,6 +50,16 @@ import {
   locationInput,
   validateRequestBody,
 } from './util';
+import { initialize } from 'express-openapi';
+import yaml from 'js-yaml';
+import fs from 'fs';
+import path from 'path';
+
+class ParsingError extends Error {
+  toString() {
+    return `ParsingError: ${this.message}`;
+  }
+}
 
 /**
  * Options used by {@link createRouter}.
@@ -94,26 +104,41 @@ export async function createRouter(
     logger.info('Catalog is running in readonly mode');
   }
 
-  if (refreshService) {
-    router.post('/refresh', async (req, res) => {
-      const refreshOptions: RefreshOptions = req.body;
-      refreshOptions.authorizationToken = getBearerToken(
-        req.header('authorization'),
-      );
+  const validateDependency = (
+    dependency: any,
+    next: (req: express.Request, res: express.Response) => any,
+  ) => {
+    return (req: express.Request, res: express.Response) => {
+      if (!dependency) {
+        console.log('no dependency');
+        throw new NotFoundError(
+          'Dependency Error',
+          'Dependency not set up for this endpoint.',
+        );
+      }
+      return next(req, res);
+    };
+  };
 
-      await refreshService.refresh(refreshOptions);
-      res.status(200).end();
-    });
-  }
+  initialize({
+    app: router as any,
+    // NOTE: If using yaml you can provide a path relative to process.cwd() e.g.
+    // apiDoc: './api-v1/api-doc.yml',
+    apiDoc: yaml.load(
+      fs.readFileSync(path.resolve(__dirname, '../../openapi.yaml'), 'utf-8'),
+    ) as any,
+    operations: {
+      RefreshEntity: validateDependency(refreshService, async (req, res) => {
+        const refreshOptions: RefreshOptions = req.body;
+        refreshOptions.authorizationToken = getBearerToken(
+          req.header('authorization'),
+        );
 
-  if (permissionIntegrationRouter) {
-    router.use(permissionIntegrationRouter);
-  }
-
-  if (entitiesCatalog) {
-    router
-      .get('/entities', async (req, res) => {
-        const { entities, pageInfo } = await entitiesCatalog.entities({
+        await refreshService!.refresh(refreshOptions);
+        res.status(200).end();
+      }),
+      GetEntities: validateDependency(entitiesCatalog, async (req, res) => {
+        const { entities, pageInfo } = await entitiesCatalog!.entities({
           filter: parseEntityFilterParams(req.query),
           fields: parseEntityTransformParams(req.query),
           order: parseEntityOrderParams(req.query),
@@ -131,30 +156,10 @@ export async function createRouter(
 
         // TODO(freben): encode the pageInfo in the response
         res.json(entities);
-      })
-      .get('/entities/by-query', async (req, res) => {
-        const { items, pageInfo, totalItems } =
-          await entitiesCatalog.queryEntities({
-            ...parseQueryEntitiesParams(req.query),
-            authorizationToken: getBearerToken(req.header('authorization')),
-          });
-
-        res.json({
-          items,
-          totalItems,
-          pageInfo: {
-            ...(pageInfo.nextCursor && {
-              nextCursor: encodeCursor(pageInfo.nextCursor),
-            }),
-            ...(pageInfo.prevCursor && {
-              prevCursor: encodeCursor(pageInfo.prevCursor),
-            }),
-          },
-        });
-      })
-      .get('/entities/by-uid/:uid', async (req, res) => {
+      }),
+      GetEntityByUid: validateDependency(entitiesCatalog, async (req, res) => {
         const { uid } = req.params;
-        const { entities } = await entitiesCatalog.entities({
+        const { entities } = await entitiesCatalog!.entities({
           filter: basicEntityFilter({ 'metadata.uid': uid }),
           authorizationToken: getBearerToken(req.header('authorization')),
         });
@@ -162,17 +167,10 @@ export async function createRouter(
           throw new NotFoundError(`No entity with uid ${uid}`);
         }
         res.status(200).json(entities[0]);
-      })
-      .delete('/entities/by-uid/:uid', async (req, res) => {
-        const { uid } = req.params;
-        await entitiesCatalog.removeEntityByUid(uid, {
-          authorizationToken: getBearerToken(req.header('authorization')),
-        });
-        res.status(204).end();
-      })
-      .get('/entities/by-name/:kind/:namespace/:name', async (req, res) => {
+      }),
+      GetEntityByName: validateDependency(entitiesCatalog, async (req, res) => {
         const { kind, namespace, name } = req.params;
-        const { entities } = await entitiesCatalog.entities({
+        const { entities } = await entitiesCatalog!.entities({
           filter: basicEntityFilter({
             kind: kind,
             'metadata.namespace': namespace,
@@ -186,41 +184,27 @@ export async function createRouter(
           );
         }
         res.status(200).json(entities[0]);
-      })
-      .get(
-        '/entities/by-name/:kind/:namespace/:name/ancestry',
+      }),
+      GetEntityAncestryByName: validateDependency(
+        entitiesCatalog,
         async (req, res) => {
           const { kind, namespace, name } = req.params;
           const entityRef = stringifyEntityRef({ kind, namespace, name });
-          const response = await entitiesCatalog.entityAncestry(entityRef, {
+          const response = await entitiesCatalog!.entityAncestry(entityRef, {
             authorizationToken: getBearerToken(req.header('authorization')),
           });
           res.status(200).json(response);
         },
-      )
-      .post('/entities/by-refs', async (req, res) => {
-        const request = entitiesBatchRequest(req);
-        const token = getBearerToken(req.header('authorization'));
-        const response = await entitiesCatalog.entitiesBatch({
-          entityRefs: request.entityRefs,
-          fields: parseEntityTransformParams(req.query, request.fields),
-          authorizationToken: token,
-        });
-        res.status(200).json(response);
-      })
-      .get('/entity-facets', async (req, res) => {
-        const response = await entitiesCatalog.facets({
+      ),
+      GetEntityFacets: validateDependency(entitiesCatalog, async (req, res) => {
+        const response = await entitiesCatalog!.facets({
           filter: parseEntityFilterParams(req.query),
           facets: parseEntityFacetParams(req.query),
           authorizationToken: getBearerToken(req.header('authorization')),
         });
         res.status(200).json(response);
-      });
-  }
-
-  if (locationService) {
-    router
-      .post('/locations', async (req, res) => {
+      }),
+      CreateLocation: validateDependency(locationService, async (req, res) => {
         const location = await validateRequestBody(req, locationInput);
         const dryRun = yn(req.query.dryRun, { default: false });
 
@@ -234,22 +218,21 @@ export async function createRouter(
           authorizationToken: getBearerToken(req.header('authorization')),
         });
         res.status(201).json(output);
-      })
-      .get('/locations', async (req, res) => {
+      }),
+      GetLocations: validateDependency(locationService, async (req, res) => {
         const locations = await locationService.listLocations({
           authorizationToken: getBearerToken(req.header('authorization')),
         });
         res.status(200).json(locations.map(l => ({ data: l })));
-      })
-
-      .get('/locations/:id', async (req, res) => {
+      }),
+      GetLocation: validateDependency(locationService, async (req, res) => {
         const { id } = req.params;
         const output = await locationService.getLocation(id, {
           authorizationToken: getBearerToken(req.header('authorization')),
         });
         res.status(200).json(output);
-      })
-      .delete('/locations/:id', async (req, res) => {
+      }),
+      DeleteLocation: validateDependency(locationService, async (req, res) => {
         disallowReadonlyMode(readonlyEnabled);
 
         const { id } = req.params;
@@ -257,74 +240,108 @@ export async function createRouter(
           authorizationToken: getBearerToken(req.header('authorization')),
         });
         res.status(204).end();
-      });
-  }
-
-  if (locationAnalyzer) {
-    router.post('/analyze-location', async (req, res) => {
-      const body = await validateRequestBody(
-        req,
-        z.object({
+      }),
+      AnalyzeLocation: validateDependency(locationService, async (req, res) => {
+        const body = await validateRequestBody(
+          req,
+          z.object({
+            location: locationInput,
+            catalogFilename: z.string().optional(),
+          }),
+        );
+        const schema = z.object({
           location: locationInput,
           catalogFilename: z.string().optional(),
-        }),
-      );
-      const schema = z.object({
-        location: locationInput,
-        catalogFilename: z.string().optional(),
-      });
-      const output = await locationAnalyzer.analyzeLocation(schema.parse(body));
-      res.status(200).json(output);
-    });
-  }
-
-  if (orchestrator) {
-    router.post('/validate-entity', async (req, res) => {
-      const bodySchema = z.object({
-        entity: z.unknown(),
-        location: z.string(),
-      });
-
-      let body: z.infer<typeof bodySchema>;
-      let entity: Entity;
-      let location: { type: string; target: string };
-      try {
-        body = await validateRequestBody(req, bodySchema);
-        entity = validateEntityEnvelope(body.entity);
-        location = parseLocationRef(body.location);
-        if (location.type !== 'url')
-          throw new TypeError(
-            `Invalid location ref ${body.location}, only 'url:<target>' is supported, e.g. url:https://host/path`,
-          );
-      } catch (err) {
-        return res.status(400).json({
-          errors: [serializeError(err)],
         });
-      }
+        const output = await locationAnalyzer!.analyzeLocation(
+          schema.parse(body),
+        );
+        res.status(200).json(output);
+      }),
+      ValidateEntity: validateDependency(orchestrator, async (req, res) => {
+        const bodySchema = z.object({
+          entity: z.unknown(),
+          location: z.string(),
+        });
 
-      const processingResult = await orchestrator.process({
-        entity: {
-          ...entity,
-          metadata: {
-            ...entity.metadata,
-            annotations: {
-              [ANNOTATION_LOCATION]: body.location,
-              [ANNOTATION_ORIGIN_LOCATION]: body.location,
-              ...entity.metadata.annotations,
+        let body: z.infer<typeof bodySchema>;
+        let entity: Entity;
+        let location: { type: string; target: string };
+        try {
+          body = await validateRequestBody(req, bodySchema);
+          entity = validateEntityEnvelope(body.entity);
+          location = parseLocationRef(body.location);
+          if (location.type !== 'url')
+            throw new TypeError(
+              `Invalid location ref ${body.location}, only 'url:<target>' is supported, e.g. url:https://host/path`,
+            );
+        } catch (err) {
+          return res.status(400).json({
+            errors: [serializeError(err)],
+          });
+        }
+
+        const processingResult = await orchestrator!.process({
+          entity: {
+            ...entity,
+            metadata: {
+              ...entity.metadata,
+              annotations: {
+                [ANNOTATION_LOCATION]: body.location,
+                [ANNOTATION_ORIGIN_LOCATION]: body.location,
+                ...entity.metadata.annotations,
+              },
             },
           },
-        },
-      });
-
-      if (!processingResult.ok)
-        res.status(400).json({
-          errors: processingResult.errors.map(e => serializeError(e)),
         });
-      return res.status(200).end();
-    });
-  }
 
-  router.use(errorHandler());
+        if (!processingResult.ok)
+          res.status(400).json({
+            errors: processingResult.errors.map(e => serializeError(e)),
+          });
+        return res.status(200).end();
+      }),
+      DeleteEntityByUid: validateDependency(
+        entitiesCatalog,
+        async (req, res) => {
+          const { uid } = req.params;
+          await entitiesCatalog!.removeEntityByUid(uid, {
+            authorizationToken: getBearerToken(req.header('authorization')),
+          });
+          res.status(204).end();
+        },
+      ),
+      GetEntitiesByRefs: validateDependency(
+        entitiesCatalog,
+        async (req, res) => {
+          const request = entitiesBatchRequest(req);
+          const token = getBearerToken(req.header('authorization'));
+          const response = await entitiesCatalog!.entitiesBatch({
+            entityRefs: request.entityRefs,
+            fields: parseEntityTransformParams(req.query, request.fields),
+            authorizationToken: token,
+          });
+          res.status(200).json(response);
+        },
+      ),
+    },
+    enableObjectCoercion: true,
+    errorMiddleware: errorHandler(),
+    errorTransformer: (openapiError, ajvError) => {
+      switch (openapiError.errorCode) {
+        case 'type.openapi.requestValidation':
+          throw new InputError(
+            `Invalid field ${openapiError.path}`,
+            new ParsingError(openapiError.message),
+          );
+      }
+      return {};
+    },
+  });
+
+  if (permissionIntegrationRouter) {
+    router.use(permissionIntegrationRouter);
+  }
   return router;
 }
 
diff --git a/yarn.lock b/yarn.lock
index 3652a87b61..859a44fda4 100644
--- a/yarn.lock
+++ b/yarn.lock
@@ -5371,11 +5371,13 @@ __metadata:
     codeowners-utils: ^1.0.2
     core-js: ^3.6.5
     express: ^4.17.1
+    express-openapi: ^12.1.0
     express-promise-router: ^4.1.0
     fast-json-stable-stringify: ^2.1.0
     fs-extra: 10.1.0
     git-url-parse: ^13.0.0
     glob: ^7.1.6
+    js-yaml: ^4.1.0
     knex: ^2.0.0
     lodash: ^4.17.21
     luxon: ^3.0.0
@@ -17590,7 +17592,7 @@ __metadata:
   languageName: node
   linkType: hard
 
-"ajv-formats@npm:^2.1.1":
+"ajv-formats@npm:^2.0.2, ajv-formats@npm:^2.1.0, ajv-formats@npm:^2.1.1":
   version: 2.1.1
   resolution: "ajv-formats@npm:2.1.1"
   dependencies:
@@ -17636,7 +17638,7 @@ __metadata:
   languageName: node
   linkType: hard
 
-"ajv@npm:^8.0.0, ajv@npm:^8.10.0, ajv@npm:^8.11.0, ajv@npm:^8.12.0, ajv@npm:^8.8.0":
+"ajv@npm:^8.0.0, ajv@npm:^8.1.0, ajv@npm:^8.10.0, ajv@npm:^8.11.0, ajv@npm:^8.12.0, ajv@npm:^8.3.0, ajv@npm:^8.4.0, ajv@npm:^8.8.0":
   version: 8.12.0
   resolution: "ajv@npm:8.12.0"
   dependencies:
@@ -20392,6 +20394,13 @@ __metadata:
   languageName: node
   linkType: hard
 
+"content-type@npm:^1.0.4":
+  version: 1.0.4
+  resolution: "content-type@npm:1.0.4"
+  checksum: 3d93585fda985d1554eca5ebd251994327608d2e200978fdbfba21c0c679914d5faf266d17027de44b34a72c7b0745b18584ecccaa7e1fdfb6a68ac7114f12e0
+  languageName: node
+  linkType: hard
+
 "content-type@npm:~1.0.4, content-type@npm:~1.0.5":
   version: 1.0.5
   resolution: "content-type@npm:1.0.5"
@@ -21787,6 +21796,15 @@ __metadata:
   languageName: node
   linkType: hard
 
+"difunc@npm:0.0.4":
+  version: 0.0.4
+  resolution: "difunc@npm:0.0.4"
+  dependencies:
+    esprima: ^4.0.0
+  checksum: 19b850dae20cba3bdf238b85fa90f79526974e7634348a3157eef3da6eb161e7f43142aa531f6be61eed1235d1f4b6a16e07912f313b5afcceee56d998c2e300
+  languageName: node
+  linkType: hard
+
 "dir-glob@npm:^3.0.1":
   version: 3.0.1
   resolution: "dir-glob@npm:3.0.1"
@@ -23687,6 +23705,24 @@ __metadata:
   languageName: node
   linkType: hard
 
+"express-normalize-query-params-middleware@npm:^0.5.0":
+  version: 0.5.1
+  resolution: "express-normalize-query-params-middleware@npm:0.5.1"
+  checksum: 20fef3a200c452cbfef25f738e8ed44704ad30f04899cce21d3984b74e4fcbeefdc5dcec3aed1a0e4e54f231c55f3cba2c3d0cc3faebfea0cab437a852bca09b
+  languageName: node
+  linkType: hard
+
+"express-openapi@npm:^12.1.0":
+  version: 12.1.0
+  resolution: "express-openapi@npm:12.1.0"
+  dependencies:
+    express-normalize-query-params-middleware: ^0.5.0
+    openapi-framework: ^12.1.0
+    openapi-types: ^12.1.0
+  checksum: 6b87b7990891b1f4d4bd3e071eddd72d7433ae770d5ad0cfbbee234a0d4e712150640ec15d8fe9d1af99b49209700c58f4694045f00bd380a569a86ba5008755
+  languageName: node
+  linkType: hard
+
 "express-prom-bundle@npm:^6.3.6":
   version: 6.6.0
   resolution: "express-prom-bundle@npm:6.6.0"
@@ -24584,6 +24620,15 @@ __metadata:
   languageName: node
   linkType: hard
 
+"fs-routes@npm:^12.0.0":
+  version: 12.0.0
+  resolution: "fs-routes@npm:12.0.0"
+  peerDependencies:
+    glob: ">=7.1.6"
+  checksum: 4e97b08584c4ee04cf00215ac5175ba6f3aeaa4fb254cd108149d675edffcf90e802ead9965a5252271f26e1a47b31c341b41e209b9d210b2a584ae2a642c466
+  languageName: node
+  linkType: hard
+
 "fs.realpath@npm:^1.0.0":
   version: 1.0.0
   resolution: "fs.realpath@npm:1.0.0"
@@ -24905,6 +24950,19 @@ __metadata:
   languageName: node
   linkType: hard
 
+"glob@npm:*, glob@npm:8.0.3":
+  version: 8.0.3
+  resolution: "glob@npm:8.0.3"
+  dependencies:
+    fs.realpath: ^1.0.0
+    inflight: ^1.0.4
+    inherits: 2
+    minimatch: ^5.0.1
+    once: ^1.3.0
+  checksum: 50bcdea19d8e79d8de5f460b1939ffc2b3299eac28deb502093fdca22a78efebc03e66bf54f0abc3d3d07d8134d19a32850288b7440d77e072aa55f9d33b18c5
+  languageName: node
+  linkType: hard
+
 "glob@npm:7.1.6":
   version: 7.1.6
   resolution: "glob@npm:7.1.6"
@@ -24919,19 +24977,6 @@ __metadata:
   languageName: node
   linkType: hard
 
-"glob@npm:8.0.3":
-  version: 8.0.3
-  resolution: "glob@npm:8.0.3"
-  dependencies:
-    fs.realpath: ^1.0.0
-    inflight: ^1.0.4
-    inherits: 2
-    minimatch: ^5.0.1
-    once: ^1.3.0
-  checksum: 50bcdea19d8e79d8de5f460b1939ffc2b3299eac28deb502093fdca22a78efebc03e66bf54f0abc3d3d07d8134d19a32850288b7440d77e072aa55f9d33b18c5
-  languageName: node
-  linkType: hard
-
 "glob@npm:^7.0.0, glob@npm:^7.1.1, glob@npm:^7.1.3, glob@npm:^7.1.4, glob@npm:^7.1.6, glob@npm:^7.1.7, glob@npm:^7.2.0":
   version: 7.2.3
   resolution: "glob@npm:7.2.3"
@@ -26591,6 +26636,13 @@ __metadata:
   languageName: node
   linkType: hard
 
+"is-dir@npm:^1.0.0":
+  version: 1.0.0
+  resolution: "is-dir@npm:1.0.0"
+  checksum: b81430f22d03318b144391ec9633abdd6fdcd8fd02509bee1ab5a20b79311505ba4344282d2cab565114779ac36626fd034168b9bd47c3be12d956ae2ca76a5c
+  languageName: node
+  linkType: hard
+
 "is-docker@npm:^2.0.0, is-docker@npm:^2.1.1":
   version: 2.2.1
   resolution: "is-docker@npm:2.2.1"
@@ -29360,7 +29412,7 @@ __metadata:
   languageName: node
   linkType: hard
 
-"lodash.merge@npm:^4.6.2":
+"lodash.merge@npm:^4.6.1, lodash.merge@npm:^4.6.2":
   version: 4.6.2
   resolution: "lodash.merge@npm:4.6.2"
   checksum: ad580b4bdbb7ca1f7abf7e1bce63a9a0b98e370cf40194b03380a46b4ed799c9573029599caebc1b14e3f24b111aef72b96674a56cfa105e0f5ac70546cdc005
@@ -31924,6 +31976,79 @@ __metadata:
   languageName: node
   linkType: hard
 
+"openapi-default-setter@npm:^12.1.0":
+  version: 12.1.0
+  resolution: "openapi-default-setter@npm:12.1.0"
+  dependencies:
+    openapi-types: ^12.1.0
+  checksum: 3b4543d7c091134690fcfc986258481b6211f17b4322552764b3a4a9725784202bc17419a524302dd1187ecea556dea4f2cb525f4a0258c2ab5ddec884bf00e2
+  languageName: node
+  linkType: hard
+
+"openapi-framework@npm:^12.1.0":
+  version: 12.1.0
+  resolution: "openapi-framework@npm:12.1.0"
+  dependencies:
+    difunc: 0.0.4
+    fs-routes: ^12.0.0
+    glob: "*"
+    is-dir: ^1.0.0
+    js-yaml: ^3.10.0
+    openapi-default-setter: ^12.1.0
+    openapi-request-coercer: ^12.1.0
+    openapi-request-validator: ^12.1.0
+    openapi-response-validator: ^12.1.0
+    openapi-schema-validator: ^12.1.0
+    openapi-security-handler: ^12.1.0
+    openapi-types: ^12.1.0
+    ts-log: ^2.1.4
+  checksum: 4cbb35e2870604c91c01f397aa2ea8fb072f648acb9a47b830d0d67c1e68bb75eadc3e97bcbe2ea994b7374ba38866b6d91734df6e2481ce42e6625d66ccc5bd
+  languageName: node
+  linkType: hard
+
+"openapi-jsonschema-parameters@npm:^12.1.0":
+  version: 12.1.0
+  resolution: "openapi-jsonschema-parameters@npm:12.1.0"
+  dependencies:
+    openapi-types: ^12.1.0
+  checksum: 9465549e132d02ad4be67326e22c9a2e3f0cf19ffa0e3c1fe69a542a675707f11c33080836b0eebd75c02501dbcb5f4130fa446d470ede3ba67b7c52e1bc341f
+  languageName: node
+  linkType: hard
+
+"openapi-request-coercer@npm:^12.1.0":
+  version: 12.1.0
+  resolution: "openapi-request-coercer@npm:12.1.0"
+  dependencies:
+    openapi-types: ^12.1.0
+    ts-log: ^2.1.4
+  checksum: 4359d4fd58b032146838aabb9762fc2ac01771e7bea4679af5a241964f3df15ddced7968e6a8d419954d166e93ad32e08f530da0d9a8483d3c4d97be7c7c848c
+  languageName: node
+  linkType: hard
+
+"openapi-request-validator@npm:^12.1.0":
+  version: 12.1.0
+  resolution: "openapi-request-validator@npm:12.1.0"
+  dependencies:
+    ajv: ^8.3.0
+    ajv-formats: ^2.1.0
+    content-type: ^1.0.4
+    openapi-jsonschema-parameters: ^12.1.0
+    openapi-types: ^12.1.0
+    ts-log: ^2.1.4
+  checksum: 794b1c15dbf04107ede7b8304e5b7c2fa183ad0c4bd65b3e0ee4d415cf508324932959f661120f1bfb58a23d88b5458dc0db868bc36f9ec44ea03b99ea9d42df
+  languageName: node
+  linkType: hard
+
+"openapi-response-validator@npm:^12.1.0":
+  version: 12.1.0
+  resolution: "openapi-response-validator@npm:12.1.0"
+  dependencies:
+    ajv: ^8.4.0
+    openapi-types: ^12.1.0
+  checksum: f07036661ac846c5d508b423d01039cd5bd33d564e053fdc039046f964fad71b03a7c9254195b1d5a8a1912fcc45dce13616af97c445c6d7b040c825e1f91de1
+  languageName: node
+  linkType: hard
+
 "openapi-sampler@npm:^1.2.1":
   version: 1.2.1
   resolution: "openapi-sampler@npm:1.2.1"
@@ -31934,7 +32059,28 @@ __metadata:
   languageName: node
   linkType: hard
 
-"openapi-types@npm:^12.0.0":
+"openapi-schema-validator@npm:^12.1.0":
+  version: 12.1.0
+  resolution: "openapi-schema-validator@npm:12.1.0"
+  dependencies:
+    ajv: ^8.1.0
+    ajv-formats: ^2.0.2
+    lodash.merge: ^4.6.1
+    openapi-types: ^12.1.0
+  checksum: 1008ef82910cc30e85132c041b269a4cc2991dad17e2d7c4cddbfb5641a15e934016bc4d1bab32f2dc79f7f3673b82b655c3634838c9ce3a8f497af3be762aa5
+  languageName: node
+  linkType: hard
+
+"openapi-security-handler@npm:^12.1.0":
+  version: 12.1.0
+  resolution: "openapi-security-handler@npm:12.1.0"
+  dependencies:
+    openapi-types: ^12.1.0
+  checksum: 07f645300fdc0ca5d01790fb77e01d8e537f6b0439f55ec9af5097d3dd044e3e0fc55ce0acb9551f04256819d7738f8c3d468645e581f7b0487648eed428d519
+  languageName: node
+  linkType: hard
+
+"openapi-types@npm:^12.0.0, openapi-types@npm:^12.1.0":
   version: 12.1.0
   resolution: "openapi-types@npm:12.1.0"
   checksum: d8f3e2bae519aa6bcf2012f4a5592b7283fe928c06f3bdc182776ce637c7ed8d5f9f342724f68c95c9572aefe21ed5e89b18a0295a703da61af5f97bd2aea9a7
@@ -38457,6 +38603,13 @@ __metadata:
   languageName: node
   linkType: hard
 
+"ts-log@npm:^2.1.4":
+  version: 2.2.5
+  resolution: "ts-log@npm:2.2.5"
+  checksum: 28f78ab15b8555d56c089dbc243327d8ce4331219956242a29fc4cb3bad6bb0cb8234dd17a292381a1b1dba99a7e4849a2181b2e1a303e8247e9f4ca4e284f2d
+  languageName: node
+  linkType: hard
+
 "ts-log@npm:^2.2.3":
   version: 2.2.3
   resolution: "ts-log@npm:2.2.3"

From d7585d4003dc93f83f38fc0d266fe79399cd774f Mon Sep 17 00:00:00 2001
From: Aramis Sennyey <sennyeya@amazon.com>
Date: Thu, 19 Jan 2023 17:17:28 -0500
Subject: [PATCH 02/61] Starting router.

Signed-off-by: Aramis Sennyey <sennyeya@amazon.com>
---
 .../src/service/createRouter.ts               |  18 +
 plugins/openapi-router-common/.eslintrc.js    |   1 +
 plugins/openapi-router-common/README.md       |   5 +
 plugins/openapi-router-common/package.json    |  37 +
 plugins/openapi-router-common/src/index.ts    |  23 +
 plugins/openapi-router-common/src/router.ts   | 357 ++++++++++
 .../openapi-router-common/src/setupTests.ts   |  16 +
 .../openapi-router-common/src/types/fields.ts |  66 ++
 .../openapi-router-common/src/types/path.ts   | 666 ++++++++++++++++++
 .../openapi-router-common/src/types/utils.ts  | 144 ++++
 yarn.lock                                     |  43 +-
 11 files changed, 1374 insertions(+), 2 deletions(-)
 create mode 100644 plugins/openapi-router-common/.eslintrc.js
 create mode 100644 plugins/openapi-router-common/README.md
 create mode 100644 plugins/openapi-router-common/package.json
 create mode 100644 plugins/openapi-router-common/src/index.ts
 create mode 100644 plugins/openapi-router-common/src/router.ts
 create mode 100644 plugins/openapi-router-common/src/setupTests.ts
 create mode 100644 plugins/openapi-router-common/src/types/fields.ts
 create mode 100644 plugins/openapi-router-common/src/types/path.ts
 create mode 100644 plugins/openapi-router-common/src/types/utils.ts

diff --git a/plugins/catalog-backend/src/service/createRouter.ts b/plugins/catalog-backend/src/service/createRouter.ts
index 6b733a0a9a..6685332002 100644
--- a/plugins/catalog-backend/src/service/createRouter.ts
+++ b/plugins/catalog-backend/src/service/createRouter.ts
@@ -54,6 +54,7 @@ import { initialize } from 'express-openapi';
 import yaml from 'js-yaml';
 import fs from 'fs';
 import path from 'path';
+import OpenAPIBackend from 'openapi-backend';
 
 class ParsingError extends Error {
   toString() {
@@ -104,6 +105,23 @@ export async function createRouter(
     logger.info('Catalog is running in readonly mode');
   }
 
+  // create api with your definition file or object
+  const api = new OpenAPIBackend({ definition: './petstore.yml' });
+
+  // register your framework specific request handlers here
+  api.register({
+    getPets: (c, req, res) => {
+      return res.status(200).json({ result: 'ok' });
+    },
+    getPetById: (c, req, res) => res.status(200).json({ result: 'ok' }),
+    validationFail: (c, req, res) =>
+      res.status(400).json({ err: c.validation.errors }),
+    notFound: (c, req, res) => res.status(404).json({ err: 'not found' }),
+  });
+
+  // initalize the backend
+  api.init();
+
   const validateDependency = (
     dependency: any,
     next: (req: express.Request, res: express.Response) => any,
diff --git a/plugins/openapi-router-common/.eslintrc.js b/plugins/openapi-router-common/.eslintrc.js
new file mode 100644
index 0000000000..e2a53a6ad2
--- /dev/null
+++ b/plugins/openapi-router-common/.eslintrc.js
@@ -0,0 +1 @@
+module.exports = require('@backstage/cli/config/eslint-factory')(__dirname);
diff --git a/plugins/openapi-router-common/README.md b/plugins/openapi-router-common/README.md
new file mode 100644
index 0000000000..cda5d7fc7f
--- /dev/null
+++ b/plugins/openapi-router-common/README.md
@@ -0,0 +1,5 @@
+# @backstage/plugin-openapi-router-common
+
+Welcome to the common package for the openapi-router plugin!
+
+_This plugin was created through the Backstage CLI_
diff --git a/plugins/openapi-router-common/package.json b/plugins/openapi-router-common/package.json
new file mode 100644
index 0000000000..a852edfcec
--- /dev/null
+++ b/plugins/openapi-router-common/package.json
@@ -0,0 +1,37 @@
+{
+  "name": "@backstage/plugin-openapi-router",
+  "description": "OpenAPI router with type completions.",
+  "version": "0.0.0",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "license": "Apache-2.0",
+  "publishConfig": {
+    "access": "public",
+    "main": "dist/index.cjs.js",
+    "module": "dist/index.esm.js",
+    "types": "dist/index.d.ts"
+  },
+  "backstage": {
+    "role": "backend-plugin"
+  },
+  "scripts": {
+    "start": "backstage-cli package start",
+    "build": "backstage-cli package build",
+    "lint": "backstage-cli package lint",
+    "test": "backstage-cli package test",
+    "clean": "backstage-cli package clean",
+    "prepack": "backstage-cli package prepack",
+    "postpack": "backstage-cli package postpack"
+  },
+  "devDependencies": {
+    "@backstage/cli": "workspace:^"
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "express": "^4.18.2",
+    "json-schema-to-ts": "^2.6.2",
+    "openapi-types": "^12.1.0"
+  }
+}
diff --git a/plugins/openapi-router-common/src/index.ts b/plugins/openapi-router-common/src/index.ts
new file mode 100644
index 0000000000..7edca76f93
--- /dev/null
+++ b/plugins/openapi-router-common/src/index.ts
@@ -0,0 +1,23 @@
+/*
+ * Copyright 2023 The Backstage Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+/**
+ * Common functionalities for the openapi-router plugin.
+ *
+ * @packageDocumentation
+ */
+
+export * from './router';
diff --git a/plugins/openapi-router-common/src/router.ts b/plugins/openapi-router-common/src/router.ts
new file mode 100644
index 0000000000..c7940cdbd0
--- /dev/null
+++ b/plugins/openapi-router-common/src/router.ts
@@ -0,0 +1,357 @@
+/*
+ * Copyright 2023 The Backstage Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { OpenAPIV3_1 } from 'openapi-types';
+import { FieldValues } from './types/fields';
+import {
+  AppendNonBlankKey,
+  FieldPath,
+  FieldPathValue,
+  Path,
+} from './types/path';
+import { IRouter, Router, IRouterMatcher } from 'express';
+import core, {
+  ParamsDictionary,
+  RequestHandler,
+} from 'express-serve-static-core';
+import { FromSchema } from 'json-schema-to-ts';
+
+type RouterFn<TFieldValues extends FieldValues> = <
+  TFieldName extends FieldPath<TFieldValues> = FieldPath<TFieldValues>,
+>(
+  name: TFieldName,
+) => null;
+
+const doc = {
+  openapi: '3.1.0',
+  info: {
+    version: '1.0.0',
+    title: 'Swagger Petstore',
+    license: {
+      name: 'MIT',
+      url: 'https://opensource.org/licenses/MIT',
+    },
+  },
+  servers: [
+    {
+      url: 'http://petstore.swagger.io/v1',
+    },
+  ],
+  paths: {
+    '/pets': {
+      get: {
+        summary: 'List all pets',
+        operationId: 'listPets',
+        tags: ['pets'],
+        parameters: [
+          {
+            name: 'limit',
+            in: 'query',
+            description: 'How many items to return at one time (max 100)',
+            required: false,
+            schema: {
+              type: 'integer',
+              format: 'int32',
+            },
+          },
+        ],
+        responses: {
+          '200': {
+            description: 'A paged array of pets',
+            headers: {
+              'x-next': {
+                description: 'A link to the next page of responses',
+                schema: {
+                  type: 'string',
+                },
+              },
+            },
+            content: {
+              'application/json': {
+                schema: {
+                  $ref: '#/components/schemas/Pets',
+                },
+              },
+            },
+          },
+          default: {
+            description: 'unexpected error',
+            content: {
+              'application/json': {
+                schema: {
+                  $ref: '#/components/schemas/Error',
+                },
+              },
+            },
+          },
+        },
+      },
+      post: {
+        summary: 'Create a pet',
+        operationId: 'createPets',
+        tags: ['pets'],
+        responses: {
+          '201': {
+            description: 'Null response',
+          },
+          default: {
+            description: 'unexpected error',
+            content: {
+              'application/json': {
+                schema: {
+                  $ref: '#/components/schemas/Error',
+                },
+              },
+            },
+          },
+        },
+      },
+    },
+    '/pets/{petId}': {
+      get: {
+        summary: 'Info for a specific pet',
+        operationId: 'showPetById',
+        tags: ['pets'],
+        parameters: [
+          {
+            name: 'petId',
+            in: 'path',
+            required: true,
+            description: 'The id of the pet to retrieve',
+            schema: {
+              type: 'string',
+            },
+          },
+        ],
+        responses: {
+          '200': {
+            description: 'Expected response to a valid request',
+            content: {
+              'application/json': {
+                schema: {
+                  $ref: '#/components/schemas/Pet',
+                },
+              },
+            },
+          },
+          default: {
+            description: 'unexpected error',
+            content: {
+              'application/json': {
+                schema: {
+                  $ref: '#/components/schemas/Error',
+                },
+              },
+            },
+          },
+        },
+      },
+    },
+  },
+  components: {
+    schemas: {
+      Pet: {
+        type: 'object',
+        required: ['id', 'name'],
+        properties: {
+          id: {
+            type: 'integer',
+            format: 'int64',
+          },
+          name: {
+            type: 'string',
+          },
+          tag: {
+            type: 'string',
+          },
+        },
+      },
+      Pets: {
+        type: 'array',
+        items: {
+          $ref: '#/components/schemas/Pet',
+        },
+      },
+      Error: {
+        type: 'object',
+        required: ['code', 'message'],
+        properties: {
+          code: {
+            type: 'integer',
+            format: 'int32',
+          },
+          message: {
+            type: 'string',
+          },
+        },
+      },
+    },
+  },
+} as const;
+
+const isUndefined = (a: any): a is undefined => a === undefined;
+const isNull = (a: any): a is null => a === null;
+
+const isNullOrUndefined = (a: any): a is undefined | null =>
+  isUndefined(a) || isNull(a);
+
+const isDateObject = (value: unknown): value is Date => value instanceof Date;
+
+const isObjectType = (value: unknown) => typeof value === 'object';
+
+const isObject = <T extends object>(value: unknown): value is T =>
+  !isNullOrUndefined(value) &&
+  !Array.isArray(value) &&
+  isObjectType(value) &&
+  !isDateObject(value);
+
+const compact = <TValue>(value: TValue[]) =>
+  Array.isArray(value) ? value.filter(Boolean) : [];
+
+export const resolve = <T>(
+  obj: T,
+  path: string,
+  defaultValue?: unknown,
+): any => {
+  if (!path || !isObject(obj)) {
+    return defaultValue;
+  }
+
+  const result = compact(path.split(/[,[\].]+?/)).reduce(
+    (result, key) =>
+      isNullOrUndefined(result) ? result : result[key as keyof {}],
+    obj,
+  );
+  if (result === undefined || result === obj) {
+    return obj[path as keyof T] === undefined
+      ? defaultValue
+      : obj[path as keyof T];
+  }
+  return result;
+};
+
+/**
+ * We want this to input path and have
+ * @param name
+ * @returns
+ */
+const x: RouterFn<typeof doc.paths> = name => {
+  console.log(resolve(doc, name));
+  return null;
+};
+
+x('/pets/{petId}');
+
+type RemoveTail<
+  S extends string,
+  Tail extends string,
+> = S extends `${infer P}${Tail}` ? P : S;
+type GetRouteParameter<S extends string> = RemoveTail<
+  RemoveTail<RemoveTail<S, `/${string}`>, `-${string}`>,
+  `.${string}`
+>;
+export type RouteParameters<Route extends string> = string extends Route
+  ? ParamsDictionary
+  : Route extends `${string}(${string}`
+  ? ParamsDictionary
+  : Route extends `${string}:${infer Rest}`
+  ? (GetRouteParameter<Rest> extends never
+      ? ParamsDictionary
+      : GetRouteParameter<Rest> extends `${infer ParamName}?`
+      ? { [P in ParamName]?: string }
+      : { [P in GetRouteParameter<Rest>]: string }) &
+      (Rest extends `${GetRouteParameter<Rest>}${infer Next}`
+        ? RouteParameters<Next>
+        : unknown)
+  : {};
+interface ParsedQs {
+  [key: string]: undefined | string | string[] | ParsedQs | ParsedQs[];
+}
+interface ApiRouterMatcher<
+  TFieldValues extends FieldValues,
+  T,
+  Method extends
+    | 'all'
+    | 'get'
+    | 'post'
+    | 'put'
+    | 'delete'
+    | 'patch'
+    | 'options'
+    | 'head',
+> {
+  <
+    TFieldName extends Path<TFieldValues> = Path<TFieldValues>,
+    P = RouteParameters<TFieldName>,
+    ResBody = any,
+    ReqBody = any,
+    ReqQuery = ParsedQs,
+    Locals extends Record<string, any> = Record<string, any>,
+  >(
+    // (it's used as the default type parameter for P)
+    path: TFieldName,
+    // (This generic is meant to be passed explicitly.)
+    ...handlers: Array<RequestHandler<P, ResBody, ReqBody, ReqQuery, Locals>>
+  ): T;
+}
+
+type path = ApiRouterMatcher<typeof doc.paths, any, 'get'>;
+const test: path = a => {
+  console.log(a);
+};
+test('/pets/{petId}');
+
+export interface IApiRouter<ApiSpec, PathSpec, T> extends IRouter {
+  all: ApiRouterMatcher<PathSpec, T, 'all'>;
+  get: ApiRouterMatcher<PathSpec, T, 'get'>;
+}
+
+export default class ApiRouter<
+  ApiSpec,
+  PathSpec extends OpenAPIV3_1.Document,
+  T,
+> implements IApiRouter<ApiSpec, PathSpec, T>
+{
+  private _router = Router();
+
+  constructor(private spec: OpenAPIV3_1.Document) {}
+
+  static fromSpec<ApiSpec, PathSpec, T>(spec: OpenAPIV3_1.Document) {
+    return new ApiRouter<ApiSpec, PathSpec, T>(spec);
+  }
+
+  get<
+    TFieldValues extends FieldValues = PathSpec,
+    TFieldName extends FieldPath<TFieldValues> = FieldPath<TFieldValues>,
+  >(
+    path: TFieldName,
+    ...handlers: core.RequestHandler<
+      core.ParamsDictionary,
+      any,
+      FieldPathValue<FieldPathValue<TFieldValues, TFieldName>, 'get'>,
+      ParsedQs,
+      Record<string, string>
+    >[]
+  ) {
+    console.log(path);
+    return this._router.get(path, ...handlers);
+  }
+}
+
+const router = ApiRouter.fromSpec<typeof doc, typeof doc.paths, any>(doc);
+
+router.get('/pets', (req, res) => {
+  req.body.tags;
+});
diff --git a/plugins/openapi-router-common/src/setupTests.ts b/plugins/openapi-router-common/src/setupTests.ts
new file mode 100644
index 0000000000..4b9026cde5
--- /dev/null
+++ b/plugins/openapi-router-common/src/setupTests.ts
@@ -0,0 +1,16 @@
+/*
+ * Copyright 2023 The Backstage Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+export {};
diff --git a/plugins/openapi-router-common/src/types/fields.ts b/plugins/openapi-router-common/src/types/fields.ts
new file mode 100644
index 0000000000..e97eeace9d
--- /dev/null
+++ b/plugins/openapi-router-common/src/types/fields.ts
@@ -0,0 +1,66 @@
+/*
+ * Copyright 2023 The Backstage Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { IsFlatObject, Noop } from './utils';
+
+export type InternalFieldName = string;
+
+export type FieldName<TFieldValues extends FieldValues> =
+  IsFlatObject<TFieldValues> extends true
+    ? Extract<keyof TFieldValues, string>
+    : string;
+
+export type CustomElement<TFieldValues extends FieldValues> = {
+  name: FieldName<TFieldValues>;
+  type?: string;
+  value?: any;
+  disabled?: boolean;
+  checked?: boolean;
+  options?: HTMLOptionsCollection;
+  files?: FileList | null;
+  focus?: Noop;
+};
+
+export type FieldValue<TFieldValues extends FieldValues> =
+  TFieldValues[InternalFieldName];
+
+export type FieldValues = Record<string, any>;
+
+export type NativeFieldValue =
+  | string
+  | number
+  | boolean
+  | null
+  | undefined
+  | unknown[];
+
+export type FieldElement<TFieldValues extends FieldValues = FieldValues> =
+  | HTMLInputElement
+  | HTMLSelectElement
+  | HTMLTextAreaElement
+  | CustomElement<TFieldValues>;
+
+export type Ref = FieldElement;
+
+export type Field = {
+  _f: {
+    ref: Ref;
+    name: InternalFieldName;
+    refs?: HTMLInputElement[];
+    mount?: boolean;
+  };
+};
+
+export type FieldRefs = Partial<Record<InternalFieldName, Field>>;
diff --git a/plugins/openapi-router-common/src/types/path.ts b/plugins/openapi-router-common/src/types/path.ts
new file mode 100644
index 0000000000..c1ffbd6378
--- /dev/null
+++ b/plugins/openapi-router-common/src/types/path.ts
@@ -0,0 +1,666 @@
+/*
+ * Copyright 2023 The Backstage Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { FieldValues } from './fields';
+import {
+  BrowserNativeObject,
+  IsAny,
+  IsNever,
+  IsEqual,
+  Primitive,
+} from './utils';
+
+/**
+ * Type alias to `string` which describes a lodash-like path through an object.
+ * E.g. `'foo.bar.0.baz'`
+ */
+export type PathString = string;
+
+/**
+ * Type which can be traversed through with a {@link PathString}.
+ * I.e. objects, arrays, and tuples
+ */
+export type Traversable = object;
+
+/**
+ * Type to query whether an array type T is a tuple type.
+ * @typeParam T - type which may be an array or tuple
+ * @example
+ * ```
+ * IsTuple<[number]> = true
+ * IsTuple<number[]> = false
+ * ```
+ */
+export type IsTuple<T extends ReadonlyArray<any>> = number extends T['length']
+  ? false
+  : true;
+
+/**
+ * Type which can be used to index an array or tuple type.
+ */
+export type ArrayKey = number;
+
+/**
+ * Type which can be used to index an object.
+ */
+export type Key = string;
+
+/**
+ * Type to assert that a type is a {@link Key}.
+ * @typeParam T - type which may be a {@link Key}
+ */
+export type AsKey<T> = Extract<T, Key>;
+
+/**
+ * Type to convert a type to a {@link Key}.
+ * @typeParam T - type which may be converted to a {@link Key}
+ */
+export type ToKey<T> = T extends ArrayKey ? `${T}` : AsKey<T>;
+
+/**
+ * Type which describes a path through an object
+ * as a list of individual {@link Key}s.
+ */
+export type PathTuple = Key[];
+
+/**
+ * Type to assert that a type is a {@link PathTuple}.
+ * @typeParam T - type which may be a {@link PathTuple}
+ */
+export type AsPathTuple<T> = Extract<T, PathTuple>;
+
+/**
+ * Type to intersect a union type.
+ * See https://fettblog.eu/typescript-union-to-intersection/
+ * @typeParam U - union
+ * @example
+ * ```
+ * UnionToIntersection<{ foo: string } | { bar: number }>
+ *   = { foo: string; bar: number }
+ * ```
+ */
+export type UnionToIntersection<U> = (
+  U extends any ? (_: U) => any : never
+) extends (_: infer I) => any
+  ? I
+  : never;
+
+/**
+ * Type which appends a {@link Key} to the {@link PathTuple} only if it is not
+ * blank, i.e. not the empty string.
+ * @typeParam PT - path
+ * @typeParam K  - key
+ * @example
+ * ```
+ * AppendNonBlankKey<['foo'], 'bar'> = ['foo', 'bar']
+ * AppendNonBlankKey<['foo'], ''> = ['foo']
+ * ```
+ */
+export type AppendNonBlankKey<
+  PT extends PathTuple,
+  K extends Key,
+> = K extends '' ? PT : [...PT, K];
+
+/**
+ * Type to implement {@link SplitPathString} tail recursively.
+ * @typeParam PS - remaining {@link PathString} which should be split into its
+ *                 individual {@link Key}s
+ * @typeParam PT - accumulator of the {@link Key}s which have been split from
+ *                 the original {@link PathString} already
+ */
+type SplitPathStringImpl<
+  PS extends PathString,
+  PT extends PathTuple,
+> = PS extends `${infer K}.${infer R}`
+  ? SplitPathStringImpl<R, AppendNonBlankKey<PT, K>>
+  : AppendNonBlankKey<PT, PS>;
+
+/**
+ * Type to split a {@link PathString} into a {@link PathTuple}.
+ * The individual {@link Key}s may be empty strings.
+ * @typeParam PS  - {@link PathString} which should be split into its
+ *                  individual {@link Key}s
+ * @example
+ * ```
+ * SplitPathString<'foo'> = ['foo']
+ * SplitPathString<'foo.bar.0.baz'> = ['foo', 'bar', '0', 'baz']
+ * SplitPathString<'.'> = []
+ * ```
+ */
+export type SplitPathString<PS extends PathString> = SplitPathStringImpl<
+  PS,
+  []
+>;
+
+/**
+ * Type to implement {@link JoinPathTuple} tail-recursively.
+ * @typeParam PT - remaining {@link Key}s which needs to be joined
+ * @typeParam PS - accumulator of the already joined {@link Key}s
+ */
+type JoinPathTupleImpl<
+  PT extends PathTuple,
+  PS extends PathString,
+> = PT extends [infer K, ...infer R]
+  ? JoinPathTupleImpl<AsPathTuple<R>, `${PS}.${AsKey<K>}`>
+  : PS;
+
+/**
+ * Type to join a {@link PathTuple} to a {@link PathString}.
+ * @typeParam PT - {@link PathTuple} which should be joined.
+ * @example
+ * ```
+ * JoinPathTuple<['foo']> = 'foo'
+ * JoinPathTuple<['foo', 'bar', '0', 'baz']> = 'foo.bar.0.baz'
+ * JoinPathTuple<[]> = never
+ * ```
+ */
+export type JoinPathTuple<PT extends PathTuple> = PT extends [
+  infer K,
+  ...infer R,
+]
+  ? JoinPathTupleImpl<AsPathTuple<R>, AsKey<K>>
+  : never;
+
+/**
+ * Type which converts all keys of an object to {@link Key}s.
+ * @typeParam T - object type
+ * @example
+ * ```
+ * MapKeys<{0: string}> = {'0': string}
+ * ```
+ */
+type MapKeys<T> = { [K in keyof T as ToKey<K>]: T[K] };
+
+/**
+ * Type to access a type by a key.
+ *  - Returns undefined if it can't be indexed by that key.
+ *  - Returns null if the type is null.
+ *  - Returns undefined if the type is not traversable.
+ * @typeParam T - type which is indexed by the key
+ * @typeParam K - key into the type
+ * ```
+ * TryAccess<{foo: string}, 'foo'> = string
+ * TryAccess<{foo: string}, 'bar'> = undefined
+ * TryAccess<null, 'foo'> = null
+ * TryAccess<string, 'foo'> = undefined
+ * ```
+ */
+type TryAccess<T, K> = K extends keyof T
+  ? T[K]
+  : T extends null
+  ? null
+  : undefined;
+
+/**
+ * Type to access an array type by a key.
+ * Returns undefined if the key is non-numeric.
+ * @typeParam T - type which is indexed by the key
+ * @typeParam K - key into the type
+ * ```
+ * TryAccessArray<string[], '0'> = string
+ * TryAccessArray<string[], 'foo'> = undefined
+ * ```
+ */
+type TryAccessArray<
+  T extends ReadonlyArray<any>,
+  K extends Key,
+> = K extends `${ArrayKey}` ? T[number] : TryAccess<T, K>;
+
+/**
+ * Type to evaluate the type which the given key points to.
+ * @typeParam T - type which is indexed by the key
+ * @typeParam K - key into the type
+ * @example
+ * ```
+ * EvaluateKey<{foo: string}, 'foo'> = string
+ * EvaluateKey<[number, string], '1'> = string
+ * EvaluateKey<string[], '1'> = string
+ * ```
+ */
+export type EvaluateKey<T, K extends Key> = T extends ReadonlyArray<any>
+  ? IsTuple<T> extends true
+    ? TryAccess<T, K>
+    : TryAccessArray<T, K>
+  : TryAccess<MapKeys<T>, K>;
+
+/**
+ * Type to evaluate the type which the given path points to.
+ * @typeParam T  - deeply nested type which is indexed by the path
+ * @typeParam PT - path into the deeply nested type
+ * @example
+ * ```
+ * EvaluatePath<{foo: {bar: string}}, ['foo', 'bar']> = string
+ * EvaluatePath<[number, string], ['1']> = string
+ * EvaluatePath<number, []> = number
+ * EvaluatePath<number, ['foo']> = undefined
+ * ```
+ */
+export type EvaluatePath<T, PT extends PathTuple> = PT extends [
+  infer K,
+  ...infer R,
+]
+  ? EvaluatePath<EvaluateKey<T, AsKey<K>>, AsPathTuple<R>>
+  : T;
+
+/**
+ * Type which given a tuple type returns its own keys, i.e. only its indices.
+ * @typeParam T - tuple type
+ * @example
+ * ```
+ * TupleKeys<[number, string]> = '0' | '1'
+ * ```
+ */
+export type TupleKeys<T extends ReadonlyArray<any>> = Exclude<
+  keyof T,
+  keyof any[]
+>;
+
+/**
+ * Type which extracts all numeric keys from an object.
+ * @typeParam T - type
+ * @example
+ * ```
+ * NumericObjectKeys<{0: string, '1': string, foo: string}> = '0' | '1'
+ * ```
+ */
+type NumericObjectKeys<T extends Traversable> = ToKey<
+  Extract<keyof T, ArrayKey | `${ArrayKey}`>
+>;
+
+/**
+ * Type which extracts all numeric keys from an object, tuple, or array.
+ * If a union is passed, it evaluates to the overlapping numeric keys.
+ * @typeParam T - type
+ * @example
+ * ```
+ * NumericKeys<{0: string, '1': string, foo: string}> = '0' | '1'
+ * NumericKeys<number[]> = `${number}`
+ * NumericKeys<[string, number]> = '0' | '1'
+ * NumericKeys<{0: string, '1': string} | [number] | number[]> = '0'
+ * ```
+ */
+export type NumericKeys<T extends Traversable> = UnionToIntersection<
+  T extends ReadonlyArray<any>
+    ? IsTuple<T> extends true
+      ? [TupleKeys<T>]
+      : [ToKey<ArrayKey>]
+    : [NumericObjectKeys<T>]
+>[never];
+
+/**
+ * Type which extracts all keys from an object.
+ * If a union is passed, it evaluates to the overlapping keys.
+ * @typeParam T - object type
+ * @example
+ * ```
+ * ObjectKeys<{foo: string, bar: string}, string> = 'foo' | 'bar'
+ * ObjectKeys<{foo: string, bar: number}, string> = 'foo'
+ * ```
+ */
+export type ObjectKeys<T extends Traversable> = Exclude<
+  ToKey<keyof T>,
+  `${string}.${string}` | ''
+>;
+
+/**
+ * Type to check whether a type's property matches the constraint type
+ * and return its key. Converts the key to a {@link Key}.
+ * @typeParam T - type whose property should be checked
+ * @typeParam K - key of the property
+ * @typeParam U - constraint type
+ * @example
+ * ```
+ * CheckKeyConstraint<{foo: string}, 'foo', string> = 'foo'
+ * CheckKeyConstraint<{foo: string}, 'foo', number> = never
+ * CheckKeyConstraint<string[], number, string> = `${number}`
+ * ```
+ */
+export type CheckKeyConstraint<T, K extends Key, U> = K extends any
+  ? EvaluateKey<T, K> extends U
+    ? K
+    : never
+  : never;
+
+/**
+ * Type which evaluates to true when the type is an array or tuple or is a union
+ * which contains an array or tuple.
+ * @typeParam T - type
+ * @example
+ * ```
+ * ContainsIndexable<{foo: string}> = false
+ * ContainsIndexable<{foo: string} | number[]> = true
+ * ```
+ */
+export type ContainsIndexable<T> = IsNever<
+  Extract<T, ReadonlyArray<any>>
+> extends true
+  ? false
+  : true;
+
+/**
+ * Type to implement {@link Keys} for non-nullable values.
+ * @typeParam T - non-nullable type whose property should be checked
+ */
+type KeysImpl<T> = [T] extends [Traversable]
+  ? ContainsIndexable<T> extends true
+    ? NumericKeys<T>
+    : ObjectKeys<T>
+  : never;
+
+/**
+ * Type to find all properties of a type that match the constraint type
+ * and return their keys.
+ * If a union is passed, it evaluates to the overlapping keys.
+ * @typeParam T - type whose property should be checked
+ * @typeParam U - constraint type
+ * @example
+ * ```
+ * Keys<{foo: string, bar: string}, string> = 'foo' | 'bar'
+ * Keys<{foo?: string, bar?: string}> = 'foo' | 'bar'
+ * Keys<{foo: string, bar: number}, string> = 'foo'
+ * Keys<[string, number], string> = '0'
+ * Keys<string[], string> = `${number}`
+ * Keys<{0: string, '1': string} | [number] | number[]> = '0'
+ * ```
+ */
+export type Keys<T, U = unknown> = IsAny<T> extends true
+  ? Key
+  : IsNever<T> extends true
+  ? Key
+  : IsNever<NonNullable<T>> extends true
+  ? never
+  : CheckKeyConstraint<T, KeysImpl<NonNullable<T>>, U>;
+
+/**
+ * Type to check whether a {@link Key} is present in a type.
+ * If a union of {@link Key}s is passed, all {@link Key}s have to be present
+ * in the type.
+ * @typeParam T - type which is introspected
+ * @typeParam K - key
+ * @example
+ * ```
+ * HasKey<{foo: string}, 'foo'> = true
+ * HasKey<{foo: string}, 'bar'> = false
+ * HasKey<{foo: string}, 'foo' | 'bar'> = false
+ * ```
+ */
+export type HasKey<T, K extends Key> = IsNever<Exclude<K, Keys<T>>>;
+
+/**
+ * Type to implement {@link ValidPathPrefix} tail recursively.
+ * @typeParam T   - type which the path should be checked against
+ * @typeParam PT  - path which should exist within the given type
+ * @typeParam VPT - accumulates the prefix of {@link Key}s which have been
+ *                  confirmed to exist already
+ */
+type ValidPathPrefixImpl<
+  T,
+  PT extends PathTuple,
+  VPT extends PathTuple,
+> = PT extends [infer K, ...infer R]
+  ? HasKey<T, AsKey<K>> extends true
+    ? ValidPathPrefixImpl<
+        EvaluateKey<T, AsKey<K>>,
+        AsPathTuple<R>,
+        AsPathTuple<[...VPT, K]>
+      >
+    : VPT
+  : VPT;
+
+/**
+ * Type to find the longest path prefix which is still valid,
+ * i.e. exists within the given type.
+ * @typeParam T  - type which the path should be checked against
+ * @typeParam PT - path which should exist within the given type
+ * @example
+ * ```
+ * ValidPathPrefix<{foo: {bar: string}}, ['foo', 'bar']> = ['foo', 'bar']
+ * ValidPathPrefix<{foo: {bar: string}}, ['foo', 'ba']> = ['foo']
+ * ```
+ */
+export type ValidPathPrefix<T, PT extends PathTuple> = ValidPathPrefixImpl<
+  T,
+  PT,
+  []
+>;
+
+/**
+ * Type to check whether a path through a type exists.
+ * @typeParam T  - type which the path should be checked against
+ * @typeParam PT - path which should exist within the given type
+ * @example
+ * ```
+ * HasPath<{foo: {bar: string}}, ['foo', 'bar']> = true
+ * HasPath<{foo: {bar: string}}, ['foo', 'ba']> = false
+ * ```
+ */
+export type HasPath<T, PT extends PathTuple> = ValidPathPrefix<T, PT> extends PT
+  ? true
+  : false;
+
+/**
+ * Helper function to break apart T1 and check if any are equal to T2
+ *
+ * See {@link IsEqual}
+ */
+type AnyIsEqual<T1, T2> = T1 extends T2
+  ? IsEqual<T1, T2> extends true
+    ? true
+    : never
+  : never;
+
+type HttpMethod = 'get' | 'post' | 'put' | 'delete' | 'all';
+
+/**
+ * Helper type for recursively constructing paths through a type.
+ * This actually constructs the strings and recurses into nested
+ * object types.
+ *
+ * See {@link Path}
+ */
+type PathImpl<K extends string | number, V, TraversedTypes> = V extends
+  | Primitive
+  | BrowserNativeObject
+  ? `${K}`
+  : // Check so that we don't recurse into the same type
+  // by ensuring that the types are mutually assignable
+  // mutually required to avoid false positives of subtypes
+  true extends AnyIsEqual<TraversedTypes, V>
+  ? `${K}`
+  : true extends AnyIsEqual<HttpMethod, K>
+  ? ``
+  : `${K}` | `${K}.${PathInternal<V, TraversedTypes | V>}`;
+
+/**
+ * Helper type for recursively constructing paths through a type.
+ * This obsucres the internal type param TraversedTypes from exported contract.
+ *
+ * See {@link Path}
+ */
+type PathInternal<T, TraversedTypes = T> = T extends ReadonlyArray<infer V>
+  ? IsTuple<T> extends true
+    ? {
+        [K in TupleKeys<T>]-?: PathImpl<K & string, T[K], TraversedTypes>;
+      }[TupleKeys<T>]
+    : PathImpl<ArrayKey, V, TraversedTypes>
+  : {
+      [K in keyof T]-?: PathImpl<K & string, T[K], TraversedTypes>;
+    }[keyof T];
+
+/**
+ * Type which eagerly collects all paths through a type
+ * @typeParam T - type which should be introspected
+ * @example
+ * ```
+ * Path<{foo: {bar: string}}> = 'foo' | 'foo.bar'
+ * ```
+ */
+// We want to explode the union type and process each individually
+// so assignable types don't leak onto the stack from the base.
+export type Path<T> = T extends any ? PathInternal<T> : never;
+
+/**
+ * See {@link Path}
+ */
+export type FieldPath<TFieldValues extends FieldValues> = Path<TFieldValues>;
+
+/**
+ * Helper type for recursively constructing paths through a type.
+ * This actually constructs the strings and recurses into nested
+ * object types.
+ *
+ * See {@link ArrayPath}
+ */
+type ArrayPathImpl<K extends string | number, V, TraversedTypes> = V extends
+  | Primitive
+  | BrowserNativeObject
+  ? IsAny<V> extends true
+    ? string
+    : never
+  : V extends ReadonlyArray<infer U>
+  ? U extends Primitive | BrowserNativeObject
+    ? IsAny<V> extends true
+      ? string
+      : never
+    : // Check so that we don't recurse into the same type
+    // by ensuring that the types are mutually assignable
+    // mutually required to avoid false positives of subtypes
+    true extends AnyIsEqual<TraversedTypes, V>
+    ? never
+    : `${K}` | `${K}.${ArrayPathInternal<V, TraversedTypes | V>}`
+  : true extends AnyIsEqual<TraversedTypes, V>
+  ? never
+  : `${K}.${ArrayPathInternal<V, TraversedTypes | V>}`;
+
+/**
+ * Helper type for recursively constructing paths through a type.
+ * This obsucres the internal type param TraversedTypes from exported contract.
+ *
+ * See {@link ArrayPath}
+ */
+type ArrayPathInternal<T, TraversedTypes = T> = T extends ReadonlyArray<infer V>
+  ? IsTuple<T> extends true
+    ? {
+        [K in TupleKeys<T>]-?: ArrayPathImpl<K & string, T[K], TraversedTypes>;
+      }[TupleKeys<T>]
+    : ArrayPathImpl<ArrayKey, V, TraversedTypes>
+  : {
+      [K in keyof T]-?: ArrayPathImpl<K & string, T[K], TraversedTypes>;
+    }[keyof T];
+
+/**
+ * Type which eagerly collects all paths through a type which point to an array
+ * type.
+ * @typeParam T - type which should be introspected.
+ * @example
+ * ```
+ * Path<{foo: {bar: string[], baz: number[]}}> = 'foo.bar' | 'foo.baz'
+ * ```
+ */
+// We want to explode the union type and process each individually
+// so assignable types don't leak onto the stack from the base.
+export type ArrayPath<T> = T extends any ? ArrayPathInternal<T> : never;
+
+/**
+ * See {@link ArrayPath}
+ */
+export type FieldArrayPath<TFieldValues extends FieldValues> =
+  ArrayPath<TFieldValues>;
+
+/**
+ * Type to evaluate the type which the given path points to.
+ * @typeParam T - deeply nested type which is indexed by the path
+ * @typeParam P - path into the deeply nested type
+ * @example
+ * ```
+ * PathValue<{foo: {bar: string}}, 'foo.bar'> = string
+ * PathValue<[number, string], '1'> = string
+ * ```
+ */
+export type PathValue<T, P extends Path<T> | ArrayPath<T>> = T extends any
+  ? P extends `${infer K}.${infer R}`
+    ? K extends keyof T
+      ? R extends Path<T[K]>
+        ? PathValue<T[K], R>
+        : never
+      : K extends `${ArrayKey}`
+      ? T extends ReadonlyArray<infer V>
+        ? PathValue<V, R & Path<V>>
+        : never
+      : never
+    : P extends keyof T
+    ? T[P]
+    : P extends `${ArrayKey}`
+    ? T extends ReadonlyArray<infer V>
+      ? V
+      : never
+    : never
+  : never;
+
+/**
+ * See {@link PathValue}
+ */
+export type FieldPathValue<
+  TFieldValues extends FieldValues,
+  TFieldPath extends FieldPath<TFieldValues>,
+> = PathValue<TFieldValues, TFieldPath>;
+
+/**
+ * See {@link PathValue}
+ */
+export type FieldArrayPathValue<
+  TFieldValues extends FieldValues,
+  TFieldArrayPath extends FieldArrayPath<TFieldValues>,
+> = PathValue<TFieldValues, TFieldArrayPath>;
+
+/**
+ * Type to evaluate the type which the given paths point to.
+ * @typeParam TFieldValues - field values which are indexed by the paths
+ * @typeParam TPath        - paths into the deeply nested field values
+ * @example
+ * ```
+ * FieldPathValues<{foo: {bar: string}}, ['foo', 'foo.bar']>
+ *   = [{bar: string}, string]
+ * ```
+ */
+export type FieldPathValues<
+  TFieldValues extends FieldValues,
+  TPath extends FieldPath<TFieldValues>[] | readonly FieldPath<TFieldValues>[],
+> = {} & {
+  [K in keyof TPath]: FieldPathValue<
+    TFieldValues,
+    TPath[K] & FieldPath<TFieldValues>
+  >;
+};
+
+/**
+ * Type which eagerly collects all paths through a fieldType that matches a give type
+ * @typeParam TFieldValues - field values which are indexed by the paths
+ * @typeParam TValue       - the value you want to match into each type
+ * @example
+ * ```typescript
+ * FieldPathByValue<{foo: {bar: number}, baz: number, bar: string}, number>
+ *   = 'foo.bar' | 'baz'
+ * ```
+ */
+export type FieldPathByValue<TFieldValues extends FieldValues, TValue> = {
+  [FieldKey in FieldPath<TFieldValues>]: FieldPathValue<
+    TFieldValues,
+    FieldKey
+  > extends TValue
+    ? FieldKey
+    : never;
+}[FieldPath<TFieldValues>];
diff --git a/plugins/openapi-router-common/src/types/utils.ts b/plugins/openapi-router-common/src/types/utils.ts
new file mode 100644
index 0000000000..25282e1da2
--- /dev/null
+++ b/plugins/openapi-router-common/src/types/utils.ts
@@ -0,0 +1,144 @@
+/*
+ * Copyright 2023 The Backstage Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+declare const $NestedValue: unique symbol;
+
+/**
+ * @deprecated to be removed in the next major version
+ */
+export type NestedValue<TValue extends object = object> = {
+  [$NestedValue]: never;
+} & TValue;
+
+/*
+Projects that React Hook Form installed don't include the DOM library need these interfaces to compile.
+React Native applications is no DOM available. The JavaScript runtime is ES6/ES2015 only.
+These definitions allow such projects to compile with only --lib ES6.
+
+Warning: all of these interfaces are empty.
+If you want type definitions for various properties, you need to add `--lib DOM` (via command line or tsconfig.json).
+*/
+
+export type Noop = () => void;
+
+interface File extends Blob {
+  readonly lastModified: number;
+  readonly name: string;
+}
+
+interface FileList {
+  readonly length: number;
+  item(index: number): File | null;
+  [index: number]: File;
+}
+
+export type Primitive =
+  | null
+  | undefined
+  | string
+  | number
+  | boolean
+  | symbol
+  | bigint;
+
+export type BrowserNativeObject = Date | FileList | File;
+
+export type EmptyObject = { [K in string | number]: never };
+
+export type NonUndefined<T> = T extends undefined ? never : T;
+
+export type LiteralUnion<T extends U, U extends Primitive> =
+  | T
+  | (U & { _?: never });
+
+export type DeepPartial<T> = T extends BrowserNativeObject | NestedValue
+  ? T
+  : { [K in keyof T]?: DeepPartial<T[K]> };
+
+export type DeepPartialSkipArrayKey<T> = T extends
+  | BrowserNativeObject
+  | NestedValue
+  ? T
+  : T extends ReadonlyArray<any>
+  ? { [K in keyof T]: DeepPartialSkipArrayKey<T[K]> }
+  : { [K in keyof T]?: DeepPartialSkipArrayKey<T[K]> };
+
+/**
+ * Checks whether the type is any
+ * See {@link https://stackoverflow.com/a/49928360/3406963}
+ * @typeParam T - type which may be any
+ * ```
+ * IsAny<any> = true
+ * IsAny<string> = false
+ * ```
+ */
+export type IsAny<T> = 0 extends 1 & T ? true : false;
+
+/**
+ * Checks whether the type is never
+ * @typeParam T - type which may be never
+ * ```
+ * IsAny<never> = true
+ * IsAny<string> = false
+ * ```
+ */
+export type IsNever<T> = [T] extends [never] ? true : false;
+
+/**
+ * Checks whether T1 can be exactly (mutually) assigned to T2
+ * @typeParam T1 - type to check
+ * @typeParam T2 - type to check against
+ * ```
+ * IsEqual<string, string> = true
+ * IsEqual<'foo', 'foo'> = true
+ * IsEqual<string, number> = false
+ * IsEqual<string, number> = false
+ * IsEqual<string, 'foo'> = false
+ * IsEqual<'foo', string> = false
+ * IsEqual<'foo' | 'bar', 'foo'> = boolean // 'foo' is assignable, but 'bar' is not (true | false) -> boolean
+ * ```
+ */
+export type IsEqual<T1, T2> = T1 extends T2
+  ? (<G>() => G extends T1 ? 1 : 2) extends <G>() => G extends T2 ? 1 : 2
+    ? true
+    : false
+  : false;
+
+export type DeepMap<T, TValue> = IsAny<T> extends true
+  ? any
+  : T extends BrowserNativeObject | NestedValue
+  ? TValue
+  : T extends object
+  ? { [K in keyof T]: DeepMap<NonUndefined<T[K]>, TValue> }
+  : TValue;
+
+export type IsFlatObject<T extends object> = Extract<
+  Exclude<T[keyof T], NestedValue | Date | FileList>,
+  any[] | object
+> extends never
+  ? true
+  : false;
+
+export type Merge<A, B> = {
+  [K in keyof A | keyof B]?: K extends keyof A & keyof B
+    ? [A[K], B[K]] extends [object, object]
+      ? Merge<A[K], B[K]>
+      : A[K] | B[K]
+    : K extends keyof A
+    ? A[K]
+    : K extends keyof B
+    ? B[K]
+    : never;
+};
diff --git a/yarn.lock b/yarn.lock
index 859a44fda4..eb39765348 100644
--- a/yarn.lock
+++ b/yarn.lock
@@ -3342,7 +3342,7 @@ __metadata:
   languageName: node
   linkType: hard
 
-"@babel/runtime@npm:^7.0.0, @babel/runtime@npm:^7.1.2, @babel/runtime@npm:^7.10.1, @babel/runtime@npm:^7.12.1, @babel/runtime@npm:^7.12.5, @babel/runtime@npm:^7.14.6, @babel/runtime@npm:^7.15.4, @babel/runtime@npm:^7.18.6, @babel/runtime@npm:^7.2.0, @babel/runtime@npm:^7.20.1, @babel/runtime@npm:^7.20.7, @babel/runtime@npm:^7.3.1, @babel/runtime@npm:^7.4.4, @babel/runtime@npm:^7.5.5, @babel/runtime@npm:^7.6.0, @babel/runtime@npm:^7.7.6, @babel/runtime@npm:^7.8.3, @babel/runtime@npm:^7.8.4, @babel/runtime@npm:^7.8.7, @babel/runtime@npm:^7.9.2":
+"@babel/runtime@npm:^7.0.0, @babel/runtime@npm:^7.1.2, @babel/runtime@npm:^7.10.1, @babel/runtime@npm:^7.12.1, @babel/runtime@npm:^7.12.5, @babel/runtime@npm:^7.14.6, @babel/runtime@npm:^7.15.4, @babel/runtime@npm:^7.18.3, @babel/runtime@npm:^7.18.6, @babel/runtime@npm:^7.2.0, @babel/runtime@npm:^7.20.1, @babel/runtime@npm:^7.20.7, @babel/runtime@npm:^7.3.1, @babel/runtime@npm:^7.4.4, @babel/runtime@npm:^7.5.5, @babel/runtime@npm:^7.6.0, @babel/runtime@npm:^7.7.6, @babel/runtime@npm:^7.8.3, @babel/runtime@npm:^7.8.4, @babel/runtime@npm:^7.8.7, @babel/runtime@npm:^7.9.2":
   version: 7.20.13
   resolution: "@babel/runtime@npm:7.20.13"
   dependencies:
@@ -7446,6 +7446,17 @@ __metadata:
   languageName: unknown
   linkType: soft
 
+"@backstage/plugin-openapi-router@workspace:plugins/openapi-router-common":
+  version: 0.0.0-use.local
+  resolution: "@backstage/plugin-openapi-router@workspace:plugins/openapi-router-common"
+  dependencies:
+    "@backstage/cli": "workspace:^"
+    express: ^4.18.2
+    json-schema-to-ts: ^2.6.2
+    openapi-types: ^12.1.0
+  languageName: unknown
+  linkType: soft
+
 "@backstage/plugin-org-react@workspace:plugins/org-react":
   version: 0.0.0-use.local
   resolution: "@backstage/plugin-org-react@workspace:plugins/org-react"
@@ -23777,7 +23788,7 @@ __metadata:
   languageName: node
   linkType: hard
 
-"express@npm:^4.17.1, express@npm:^4.17.3, express@npm:^4.18.1":
+"express@npm:^4.17.1, express@npm:^4.17.3, express@npm:^4.18.1, express@npm:^4.18.2":
   version: 4.18.2
   resolution: "express@npm:4.18.2"
   dependencies:
@@ -28324,6 +28335,18 @@ __metadata:
   languageName: node
   linkType: hard
 
+"json-schema-to-ts@npm:^2.6.2":
+  version: 2.6.2
+  resolution: "json-schema-to-ts@npm:2.6.2"
+  dependencies:
+    "@babel/runtime": ^7.18.3
+    "@types/json-schema": ^7.0.9
+    ts-algebra: ^1.1.1
+    ts-toolbelt: ^9.6.0
+  checksum: e408f8d3d32dda1a001f194cf5514fea7ef0a4dc4ed4f5448b9ea02df3a071119a0517aaffb639de725f4a12102406dfdf7743455e0e30317e231bb551362039
+  languageName: node
+  linkType: hard
+
 "json-schema-traverse@npm:^0.4.1":
   version: 0.4.1
   resolution: "json-schema-traverse@npm:0.4.1"
@@ -38580,6 +38603,15 @@ __metadata:
   languageName: node
   linkType: hard
 
+"ts-algebra@npm:^1.1.1":
+  version: 1.1.1
+  resolution: "ts-algebra@npm:1.1.1"
+  dependencies:
+    ts-toolbelt: ^9.6.0
+  checksum: 29fe27215863520377a94a14ccf1e78e921be6a5c514a0a8250dab09e325b006a9571ef1f366875d58e495b59ba880620718a1dd38b6af598cc6ea6de82d4f66
+  languageName: node
+  linkType: hard
+
 "ts-easing@npm:^0.2.0":
   version: 0.2.0
   resolution: "ts-easing@npm:0.2.0"
@@ -38672,6 +38704,13 @@ __metadata:
   languageName: node
   linkType: hard
 
+"ts-toolbelt@npm:^9.6.0":
+  version: 9.6.0
+  resolution: "ts-toolbelt@npm:9.6.0"
+  checksum: 9f35fd95d895a5d32ea9fd2e532a695b0bae6cbff6832b77292efa188a0ed1ed6e54f63f74a8920390f3d909a7a3adb20a144686372a8e78b420246a9bd3d58a
+  languageName: node
+  linkType: hard
+
 "tsconfig-paths@npm:^3.14.1":
   version: 3.14.1
   resolution: "tsconfig-paths@npm:3.14.1"

From ef4d42ec301f586560b2a195d23a091acb8d06e9 Mon Sep 17 00:00:00 2001
From: Aramis Sennyey <sennyeya@amazon.com>
Date: Thu, 19 Jan 2023 18:51:12 -0500
Subject: [PATCH 03/61] Testing

Signed-off-by: Aramis Sennyey <sennyeya@amazon.com>
---
 plugins/openapi-router-common/src/router.ts | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/plugins/openapi-router-common/src/router.ts b/plugins/openapi-router-common/src/router.ts
index c7940cdbd0..740dc8dc03 100644
--- a/plugins/openapi-router-common/src/router.ts
+++ b/plugins/openapi-router-common/src/router.ts
@@ -340,7 +340,7 @@ export default class ApiRouter<
     ...handlers: core.RequestHandler<
       core.ParamsDictionary,
       any,
-      FieldPathValue<FieldPathValue<TFieldValues, TFieldName>, 'get'>,
+      FieldPathValue<TFieldValues, TFieldName>,
       ParsedQs,
       Record<string, string>
     >[]

From e1962a4f0a0db599e9a5a66307f603d7ebf7753b Mon Sep 17 00:00:00 2001
From: Aramis Sennyey <sennyeya@amazon.com>
Date: Thu, 16 Feb 2023 16:13:26 -0500
Subject: [PATCH 04/61] Ading server testing and better handlers.

Signed-off-by: Aramis Sennyey <sennyeya@amazon.com>
---
 .../src/service/createRouter.ts               |  33 +-
 plugins/openapi-router-common/package.json    |   4 +-
 plugins/openapi-router-common/src/router.ts   | 295 ++++----
 plugins/openapi-router-common/src/run.ts      |  33 +
 .../src/standaloneServer.ts                   |  48 ++
 .../openapi-router-common/src/types/common.ts | 116 +++
 .../openapi-router-common/src/types/fields.ts |  66 --
 .../openapi-router-common/src/types/index.ts  |   2 +
 .../openapi-router-common/src/types/path.ts   | 666 ------------------
 .../src/types/requests.ts                     |  36 +
 .../src/types/response.ts                     |  68 ++
 .../openapi-router-common/src/types/utils.ts  | 144 ----
 yarn.lock                                     |  11 +
 13 files changed, 491 insertions(+), 1031 deletions(-)
 create mode 100644 plugins/openapi-router-common/src/run.ts
 create mode 100644 plugins/openapi-router-common/src/standaloneServer.ts
 create mode 100644 plugins/openapi-router-common/src/types/common.ts
 delete mode 100644 plugins/openapi-router-common/src/types/fields.ts
 create mode 100644 plugins/openapi-router-common/src/types/index.ts
 delete mode 100644 plugins/openapi-router-common/src/types/path.ts
 create mode 100644 plugins/openapi-router-common/src/types/requests.ts
 create mode 100644 plugins/openapi-router-common/src/types/response.ts
 delete mode 100644 plugins/openapi-router-common/src/types/utils.ts

diff --git a/plugins/catalog-backend/src/service/createRouter.ts b/plugins/catalog-backend/src/service/createRouter.ts
index 6685332002..f6c2e441e5 100644
--- a/plugins/catalog-backend/src/service/createRouter.ts
+++ b/plugins/catalog-backend/src/service/createRouter.ts
@@ -54,7 +54,6 @@ import { initialize } from 'express-openapi';
 import yaml from 'js-yaml';
 import fs from 'fs';
 import path from 'path';
-import OpenAPIBackend from 'openapi-backend';
 
 class ParsingError extends Error {
   toString() {
@@ -105,23 +104,6 @@ export async function createRouter(
     logger.info('Catalog is running in readonly mode');
   }
 
-  // create api with your definition file or object
-  const api = new OpenAPIBackend({ definition: './petstore.yml' });
-
-  // register your framework specific request handlers here
-  api.register({
-    getPets: (c, req, res) => {
-      return res.status(200).json({ result: 'ok' });
-    },
-    getPetById: (c, req, res) => res.status(200).json({ result: 'ok' }),
-    validationFail: (c, req, res) =>
-      res.status(400).json({ err: c.validation.errors }),
-    notFound: (c, req, res) => res.status(404).json({ err: 'not found' }),
-  });
-
-  // initalize the backend
-  api.init();
-
   const validateDependency = (
     dependency: any,
     next: (req: express.Request, res: express.Response) => any,
@@ -143,6 +125,7 @@ export async function createRouter(
     // NOTE: If using yaml you can provide a path relative to process.cwd() e.g.
     // apiDoc: './api-v1/api-doc.yml',
     apiDoc: yaml.load(
+      // eslint-disable-next-line no-restricted-syntax
       fs.readFileSync(path.resolve(__dirname, '../../openapi.yaml'), 'utf-8'),
     ) as any,
     operations: {
@@ -345,12 +328,18 @@ export async function createRouter(
     },
     enableObjectCoercion: true,
     errorMiddleware: errorHandler(),
-    errorTransformer: (openapiError, ajvError) => {
-      switch (openapiError.errorCode) {
+    errorTransformer: openapiError => {
+      const error = openapiError as {
+        errorCode: string;
+        path: string;
+        message: string;
+      };
+      // eslint-disable-next-line default-case
+      switch (error.errorCode) {
         case 'type.openapi.requestValidation':
           throw new InputError(
-            `Invalid field ${openapiError.path}`,
-            new ParsingError(openapiError.message),
+            `Invalid field ${error.path}`,
+            new ParsingError(error.message),
           );
       }
       return {};
diff --git a/plugins/openapi-router-common/package.json b/plugins/openapi-router-common/package.json
index a852edfcec..3a40ddecd0 100644
--- a/plugins/openapi-router-common/package.json
+++ b/plugins/openapi-router-common/package.json
@@ -32,6 +32,8 @@
   "dependencies": {
     "express": "^4.18.2",
     "json-schema-to-ts": "^2.6.2",
-    "openapi-types": "^12.1.0"
+    "openapi-types": "^12.1.0",
+    "openapi3-ts": "^3.1.2",
+    "ts-node": "^10.9.1"
   }
 }
diff --git a/plugins/openapi-router-common/src/router.ts b/plugins/openapi-router-common/src/router.ts
index 740dc8dc03..99a45b8e0c 100644
--- a/plugins/openapi-router-common/src/router.ts
+++ b/plugins/openapi-router-common/src/router.ts
@@ -13,26 +13,23 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-import { OpenAPIV3_1 } from 'openapi-types';
-import { FieldValues } from './types/fields';
+import { OpenAPIV3, OpenAPIV3_1 } from 'openapi-types';
+import { IRouter, Router } from 'express';
+import core, { ParamsDictionary } from 'express-serve-static-core';
+import { FromSchema, JSONSchema7 } from 'json-schema-to-ts';
 import {
-  AppendNonBlankKey,
-  FieldPath,
-  FieldPathValue,
-  Path,
-} from './types/path';
-import { IRouter, Router, IRouterMatcher } from 'express';
-import core, {
-  ParamsDictionary,
-  RequestHandler,
-} from 'express-serve-static-core';
-import { FromSchema } from 'json-schema-to-ts';
+  DocPath,
+  DocPathMethod,
+  DocPathTemplate,
+  MethodAwareDocPath,
+  PathTemplate,
+  RequestBodySchema,
+  RequiredDoc,
+  ValueOf,
+} from './types';
+import { ResponseSchemas } from './types/response';
 
-type RouterFn<TFieldValues extends FieldValues> = <
-  TFieldName extends FieldPath<TFieldValues> = FieldPath<TFieldValues>,
->(
-  name: TFieldName,
-) => null;
+type DeepWriteable<T> = { -readonly [P in keyof T]: DeepWriteable<T[P]> };
 
 const doc = {
   openapi: '3.1.0',
@@ -201,59 +198,6 @@ const doc = {
   },
 } as const;
 
-const isUndefined = (a: any): a is undefined => a === undefined;
-const isNull = (a: any): a is null => a === null;
-
-const isNullOrUndefined = (a: any): a is undefined | null =>
-  isUndefined(a) || isNull(a);
-
-const isDateObject = (value: unknown): value is Date => value instanceof Date;
-
-const isObjectType = (value: unknown) => typeof value === 'object';
-
-const isObject = <T extends object>(value: unknown): value is T =>
-  !isNullOrUndefined(value) &&
-  !Array.isArray(value) &&
-  isObjectType(value) &&
-  !isDateObject(value);
-
-const compact = <TValue>(value: TValue[]) =>
-  Array.isArray(value) ? value.filter(Boolean) : [];
-
-export const resolve = <T>(
-  obj: T,
-  path: string,
-  defaultValue?: unknown,
-): any => {
-  if (!path || !isObject(obj)) {
-    return defaultValue;
-  }
-
-  const result = compact(path.split(/[,[\].]+?/)).reduce(
-    (result, key) =>
-      isNullOrUndefined(result) ? result : result[key as keyof {}],
-    obj,
-  );
-  if (result === undefined || result === obj) {
-    return obj[path as keyof T] === undefined
-      ? defaultValue
-      : obj[path as keyof T];
-  }
-  return result;
-};
-
-/**
- * We want this to input path and have
- * @param name
- * @returns
- */
-const x: RouterFn<typeof doc.paths> = name => {
-  console.log(resolve(doc, name));
-  return null;
-};
-
-x('/pets/{petId}');
-
 type RemoveTail<
   S extends string,
   Tail extends string,
@@ -279,79 +223,166 @@ export type RouteParameters<Route extends string> = string extends Route
 interface ParsedQs {
   [key: string]: undefined | string | string[] | ParsedQs | ParsedQs[];
 }
-interface ApiRouterMatcher<
-  TFieldValues extends FieldValues,
+
+// oh boy don't do this
+type UnionToIntersection<U> = (U extends any ? (k: U) => void : never) extends (
+  k: infer I,
+) => void
+  ? I
+  : never;
+type LastOf<T> = UnionToIntersection<
+  T extends any ? () => T : never
+> extends () => infer R
+  ? R
+  : never;
+
+// TS4.0+
+type Push<T extends any[], V> = [...T, V];
+
+// TS4.1+
+type TuplifyUnion<
   T,
-  Method extends
-    | 'all'
-    | 'get'
-    | 'post'
-    | 'put'
-    | 'delete'
-    | 'patch'
-    | 'options'
-    | 'head',
-> {
-  <
-    TFieldName extends Path<TFieldValues> = Path<TFieldValues>,
-    P = RouteParameters<TFieldName>,
-    ResBody = any,
-    ReqBody = any,
-    ReqQuery = ParsedQs,
-    Locals extends Record<string, any> = Record<string, any>,
-  >(
-    // (it's used as the default type parameter for P)
-    path: TFieldName,
-    // (This generic is meant to be passed explicitly.)
-    ...handlers: Array<RequestHandler<P, ResBody, ReqBody, ReqQuery, Locals>>
-  ): T;
-}
+  L = LastOf<T>,
+  N = [T] extends [never] ? true : false,
+> = true extends N ? [] : Push<TuplifyUnion<Exclude<T, L>>, L>;
 
-type path = ApiRouterMatcher<typeof doc.paths, any, 'get'>;
-const test: path = a => {
-  console.log(a);
-};
-test('/pets/{petId}');
+type ConvertAll<T, R extends ReadonlyArray<unknown> = []> = T extends [
+  infer First extends JSONSchema7,
+  ...infer Rest,
+]
+  ? ConvertAll<Rest, [...R, FromSchema<First>]>
+  : R;
 
-export interface IApiRouter<ApiSpec, PathSpec, T> extends IRouter {
-  all: ApiRouterMatcher<PathSpec, T, 'all'>;
-  get: ApiRouterMatcher<PathSpec, T, 'get'>;
-}
+type ResponseToJsonSchema<
+  Doc extends RequiredDoc,
+  Path extends PathTemplate<Extract<keyof Doc['paths'], string>>,
+  Method extends DocPathMethod<Doc, Path>,
+> = ConvertAll<
+  TuplifyUnion<ValueOf<ResponseSchemas<Doc, Path, Method>>>
+>[number];
 
-export default class ApiRouter<
-  ApiSpec,
-  PathSpec extends OpenAPIV3_1.Document,
-  T,
-> implements IApiRouter<ApiSpec, PathSpec, T>
-{
+type DocRequestHandler<
+  Doc extends RequiredDoc,
+  Path extends DocPathTemplate<Doc>,
+  Method extends keyof Doc['paths'][Path],
+> = core.RequestHandler<
+  core.ParamsDictionary,
+  // From https://stackoverflow.com/questions/71393738/typescript-intersection-not-union-type-from-json-schema.
+  ResponseToJsonSchema<Doc, Path, Method>,
+  RequestBodySchema<Doc, Path, Method>,
+  ParsedQs,
+  Record<string, string>
+>;
+
+export default class ApiRouter<Doc extends RequiredDoc> {
   private _router = Router();
 
-  constructor(private spec: OpenAPIV3_1.Document) {}
+  constructor(private spec: OpenAPIV3_1.Document | OpenAPIV3.Document) {}
 
-  static fromSpec<ApiSpec, PathSpec, T>(spec: OpenAPIV3_1.Document) {
-    return new ApiRouter<ApiSpec, PathSpec, T>(spec);
+  static fromSpec<Doc extends RequiredDoc>(
+    spec: OpenAPIV3_1.Document | OpenAPIV3.Document,
+  ) {
+    return new ApiRouter<Doc>(spec);
   }
 
-  get<
-    TFieldValues extends FieldValues = PathSpec,
-    TFieldName extends FieldPath<TFieldValues> = FieldPath<TFieldValues>,
-  >(
-    path: TFieldName,
-    ...handlers: core.RequestHandler<
-      core.ParamsDictionary,
-      any,
-      FieldPathValue<TFieldValues, TFieldName>,
-      ParsedQs,
-      Record<string, string>
-    >[]
+  get<Path extends MethodAwareDocPath<Doc, DocPathTemplate<Doc>, 'get'>>(
+    path: Path,
+    ...handlers: DocRequestHandler<Doc, Path, 'get'>[]
   ) {
     console.log(path);
-    return this._router.get(path, ...handlers);
+    this._router.get(path, ...handlers);
+    return this;
+  }
+
+  post<Path extends MethodAwareDocPath<Doc, DocPathTemplate<Doc>, 'post'>>(
+    path: Path,
+    ...handlers: DocRequestHandler<Doc, Path, 'post'>[]
+  ) {
+    console.log(path);
+    this._router.post(path, ...handlers);
+    return this;
+  }
+
+  all<Path extends MethodAwareDocPath<Doc, DocPathTemplate<Doc>, 'all'>>(
+    path: Path,
+    ...handlers: DocRequestHandler<Doc, Path, 'all'>[]
+  ) {
+    console.log(path);
+    this._router.all(path, ...handlers);
+    return this;
+  }
+
+  put<Path extends MethodAwareDocPath<Doc, DocPathTemplate<Doc>, 'put'>>(
+    path: Path,
+    ...handlers: DocRequestHandler<Doc, Path, 'put'>[]
+  ) {
+    console.log(path);
+    this._router.put(path, ...handlers);
+    return this;
+  }
+  delete<Path extends MethodAwareDocPath<Doc, DocPathTemplate<Doc>, 'delete'>>(
+    path: Path,
+    ...handlers: DocRequestHandler<Doc, Path, 'delete'>[]
+  ) {
+    console.log(path);
+    this._router.delete(path, ...handlers);
+    return this;
+  }
+  patch<Path extends MethodAwareDocPath<Doc, DocPathTemplate<Doc>, 'patch'>>(
+    path: Path,
+    ...handlers: DocRequestHandler<Doc, Path, 'patch'>[]
+  ) {
+    console.log(path);
+    this._router.patch(path, ...handlers);
+    return this;
+  }
+  options<
+    Path extends MethodAwareDocPath<Doc, DocPathTemplate<Doc>, 'options'>,
+  >(path: Path, ...handlers: DocRequestHandler<Doc, Path, 'options'>[]) {
+    console.log(path);
+    this._router.options(path, ...handlers);
+    return this;
+  }
+  head<Path extends MethodAwareDocPath<Doc, DocPathTemplate<Doc>, 'head'>>(
+    path: Path,
+    ...handlers: DocRequestHandler<Doc, Path, 'head'>[]
+  ) {
+    console.log(path);
+    this._router.head(path, ...handlers);
+    return this;
+  }
+
+  use(...handlers: core.RequestHandler[]) {
+    return this._router.use(handlers);
+  }
+
+  build() {
+    return this._router;
   }
 }
 
-const router = ApiRouter.fromSpec<typeof doc, typeof doc.paths, any>(doc);
+interface RouterOptions {}
 
-router.get('/pets', (req, res) => {
-  req.body.tags;
-});
+export async function createRouter(options: RouterOptions) {
+  const router = ApiRouter.fromSpec<DeepWriteable<typeof doc>>(
+    // As const forces the doc to readonly which conflicts with imported types.
+    doc as DeepWriteable<typeof doc>,
+  );
+
+  router.get('/pets/:uid', (req, res) => {
+    res.json({
+      id: 1,
+      name: req.params['uid'],
+    });
+  });
+
+  // router.get('/pet') will complain with a TS error
+
+  router.post('/pets', (req, res) => {
+    res.json({
+      message: req.path,
+      code: 1,
+    });
+  });
+  return router.build();
+}
diff --git a/plugins/openapi-router-common/src/run.ts b/plugins/openapi-router-common/src/run.ts
new file mode 100644
index 0000000000..9a14d0e57d
--- /dev/null
+++ b/plugins/openapi-router-common/src/run.ts
@@ -0,0 +1,33 @@
+/*
+ * Copyright 2020 The Backstage Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import yn from 'yn';
+import { getRootLogger } from '@backstage/backend-common';
+import { startStandaloneServer } from './standaloneServer';
+
+const port = process.env.PLUGIN_PORT ? Number(process.env.PLUGIN_PORT) : 3004;
+const enableCors = yn(process.env.PLUGIN_CORS, { default: false });
+const logger = getRootLogger();
+
+startStandaloneServer({ port, enableCors, logger }).catch(err => {
+  logger.error(err);
+  process.exit(1);
+});
+
+process.on('SIGINT', () => {
+  logger.info('CTRL+C pressed; exiting.');
+  process.exit(0);
+});
diff --git a/plugins/openapi-router-common/src/standaloneServer.ts b/plugins/openapi-router-common/src/standaloneServer.ts
new file mode 100644
index 0000000000..aef8f006ff
--- /dev/null
+++ b/plugins/openapi-router-common/src/standaloneServer.ts
@@ -0,0 +1,48 @@
+/*
+ * Copyright 2020 The Backstage Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { Server } from 'http';
+import { Logger } from 'winston';
+import { createServiceBuilder } from '@backstage/backend-common';
+import { createRouter } from './router';
+
+export interface ServerOptions {
+  port: number;
+  enableCors: boolean;
+  logger: Logger;
+}
+
+export async function startStandaloneServer(
+  options: ServerOptions,
+): Promise<Server> {
+  const logger = options.logger.child({ service: 'app-backend' });
+  logger.debug('Starting application server...');
+  const router = await createRouter({
+    logger,
+    appPackageName: 'example-app',
+  });
+
+  const service = createServiceBuilder(module)
+    .setPort(options.port)
+    .addRouter('', router);
+
+  return await service.start().catch(err => {
+    logger.error(err);
+    process.exit(1);
+  });
+}
+
+module.hot?.accept();
diff --git a/plugins/openapi-router-common/src/types/common.ts b/plugins/openapi-router-common/src/types/common.ts
new file mode 100644
index 0000000000..2f0d6735a4
--- /dev/null
+++ b/plugins/openapi-router-common/src/types/common.ts
@@ -0,0 +1,116 @@
+/**
+ * Pulled from https://github.com/varanauskas/oatx.
+ */
+
+import type {
+  ContentObject,
+  OpenAPIObject,
+  ReferenceObject,
+} from 'openapi3-ts';
+
+export type RequiredDoc = Pick<OpenAPIObject, 'paths' | 'components'>;
+export type PathDoc = { paths: Record<string, unknown> };
+
+/**
+ * Get value types of `T`
+ */
+export type ValueOf<T> = T[keyof T];
+
+/**
+ * Validate a string against OpenAPI path template
+ * ```
+ * const path = PathTemplate<"/posts/{postId}/comments/{commentId}"> = "/posts/1/comments/2"const pathWithParams: PathTemplate<"/posts/{postId}/comments/{commentId}"> = "/posts/1/comments/2";
+ * const pathWithoutParams: PathTemplate<"/posts/comments"> = "/posts/comments";```
+ * https://spec.openapis.org/oas/v3.1.0#path-templating-matching
+ */
+export type PathTemplate<Path extends string> =
+  Path extends `${infer Prefix}{${string}}${infer Suffix}`
+    ? `${Prefix}${string}${PathTemplate<Suffix>}`
+    : Path;
+
+/**
+ * Extract path as specified in OpenAPI `Doc` based on request path
+ * ```
+ * const spec = {
+ *   paths: {
+ *       "/posts/{postId}/comments/{commentId}": {},
+ *       "/posts/comments": {},
+ *   }
+ * };
+ * const specPathWithParams: DocPath<typeof spec, "/posts/1/comments/2"> = "/posts/{postId}/comments/{commentId}";
+ * const specPathWithoutParams: DocPath<typeof spec, "/posts/comments"> = "/posts/comments";
+ * ```
+ */
+export type DocPath<
+  Doc extends PathDoc,
+  Path extends PathTemplate<Extract<keyof Doc['paths'], string>>,
+> = ValueOf<{
+  [Template in Extract<
+    keyof Doc['paths'],
+    string
+  >]: Path extends PathTemplate<Template> ? Template : never;
+}>;
+
+export type DocPathTemplate<Doc extends PathDoc> = PathTemplate<
+  Extract<keyof Doc['paths'], string>
+>;
+
+export type DocPathMethod<
+  Doc extends Pick<RequiredDoc, 'paths'>,
+  Path extends DocPathTemplate<Doc>,
+> = keyof Doc['paths'][DocPath<Doc, Path>];
+
+export type MethodAwareDocPath<
+  Doc extends PathDoc,
+  Path extends PathTemplate<Extract<keyof Doc['paths'], string>>,
+  Method extends keyof Doc['paths'][Path],
+> = ValueOf<{
+  [Template in Extract<
+    keyof Doc['paths'],
+    string
+  >]: Path extends PathTemplate<Template>
+    ? Method extends DocPathMethod<Doc, Path>
+      ? PathTemplate<Template>
+      : never
+    : never;
+}>;
+
+export type DocOperation<
+  Doc extends RequiredDoc,
+  Path extends keyof Doc['paths'],
+  Method extends keyof Doc['paths'][Path],
+> = Doc['paths'][Path][Method];
+
+export type ComponentTypes<Doc extends RequiredDoc> = Extract<
+  keyof Doc['components'],
+  string
+>;
+
+export type ComponentRef<
+  Doc extends RequiredDoc,
+  Type extends ComponentTypes<Doc>,
+  Ref extends ReferenceObject,
+> = Ref extends { $ref: `#/components/${Type}/${infer Name}` }
+  ? Name extends keyof Doc['components'][Type]
+    ? Doc['components'][Type][Name] extends ReferenceObject
+      ? ComponentRef<Doc, Type, Doc['components'][Type][Name]>
+      : Doc['components'][Type][Name]
+    : never
+  : never;
+
+export type SchemaRef<Doc extends RequiredDoc, Schema> = Schema extends {
+  $ref: `#/components/schemas/${infer Name}`;
+}
+  ? 'schemas' extends keyof Doc['components']
+    ? Name extends keyof Doc['components']['schemas']
+      ? SchemaRef<Doc, Doc['components']['schemas'][Name]>
+      : never
+    : never
+  : { [Key in keyof Schema]: SchemaRef<Doc, Schema[Key]> };
+
+export type ObjectWithContentSchema<
+  Doc extends RequiredDoc,
+  Object extends { content?: ContentObject },
+> = Object['content'] extends ContentObject
+  ? SchemaRef<Doc, Object['content']['application/json']['schema']>
+  : never;
diff --git a/plugins/openapi-router-common/src/types/fields.ts b/plugins/openapi-router-common/src/types/fields.ts
deleted file mode 100644
index e97eeace9d..0000000000
--- a/plugins/openapi-router-common/src/types/fields.ts
+++ /dev/null
@@ -1,66 +0,0 @@
-/*
- * Copyright 2023 The Backstage Authors
- *
- * Licensed under the Apache License, Version 2.0 (the "License");
- * you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- *     http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
- */
-import { IsFlatObject, Noop } from './utils';
-
-export type InternalFieldName = string;
-
-export type FieldName<TFieldValues extends FieldValues> =
-  IsFlatObject<TFieldValues> extends true
-    ? Extract<keyof TFieldValues, string>
-    : string;
-
-export type CustomElement<TFieldValues extends FieldValues> = {
-  name: FieldName<TFieldValues>;
-  type?: string;
-  value?: any;
-  disabled?: boolean;
-  checked?: boolean;
-  options?: HTMLOptionsCollection;
-  files?: FileList | null;
-  focus?: Noop;
-};
-
-export type FieldValue<TFieldValues extends FieldValues> =
-  TFieldValues[InternalFieldName];
-
-export type FieldValues = Record<string, any>;
-
-export type NativeFieldValue =
-  | string
-  | number
-  | boolean
-  | null
-  | undefined
-  | unknown[];
-
-export type FieldElement<TFieldValues extends FieldValues = FieldValues> =
-  | HTMLInputElement
-  | HTMLSelectElement
-  | HTMLTextAreaElement
-  | CustomElement<TFieldValues>;
-
-export type Ref = FieldElement;
-
-export type Field = {
-  _f: {
-    ref: Ref;
-    name: InternalFieldName;
-    refs?: HTMLInputElement[];
-    mount?: boolean;
-  };
-};
-
-export type FieldRefs = Partial<Record<InternalFieldName, Field>>;
diff --git a/plugins/openapi-router-common/src/types/index.ts b/plugins/openapi-router-common/src/types/index.ts
new file mode 100644
index 0000000000..758a48738d
--- /dev/null
+++ b/plugins/openapi-router-common/src/types/index.ts
@@ -0,0 +1,2 @@
+export * from './common';
+export * from './requests';
diff --git a/plugins/openapi-router-common/src/types/path.ts b/plugins/openapi-router-common/src/types/path.ts
deleted file mode 100644
index c1ffbd6378..0000000000
--- a/plugins/openapi-router-common/src/types/path.ts
+++ /dev/null
@@ -1,666 +0,0 @@
-/*
- * Copyright 2023 The Backstage Authors
- *
- * Licensed under the Apache License, Version 2.0 (the "License");
- * you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- *     http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
- */
-
-import { FieldValues } from './fields';
-import {
-  BrowserNativeObject,
-  IsAny,
-  IsNever,
-  IsEqual,
-  Primitive,
-} from './utils';
-
-/**
- * Type alias to `string` which describes a lodash-like path through an object.
- * E.g. `'foo.bar.0.baz'`
- */
-export type PathString = string;
-
-/**
- * Type which can be traversed through with a {@link PathString}.
- * I.e. objects, arrays, and tuples
- */
-export type Traversable = object;
-
-/**
- * Type to query whether an array type T is a tuple type.
- * @typeParam T - type which may be an array or tuple
- * @example
- * ```
- * IsTuple<[number]> = true
- * IsTuple<number[]> = false
- * ```
- */
-export type IsTuple<T extends ReadonlyArray<any>> = number extends T['length']
-  ? false
-  : true;
-
-/**
- * Type which can be used to index an array or tuple type.
- */
-export type ArrayKey = number;
-
-/**
- * Type which can be used to index an object.
- */
-export type Key = string;
-
-/**
- * Type to assert that a type is a {@link Key}.
- * @typeParam T - type which may be a {@link Key}
- */
-export type AsKey<T> = Extract<T, Key>;
-
-/**
- * Type to convert a type to a {@link Key}.
- * @typeParam T - type which may be converted to a {@link Key}
- */
-export type ToKey<T> = T extends ArrayKey ? `${T}` : AsKey<T>;
-
-/**
- * Type which describes a path through an object
- * as a list of individual {@link Key}s.
- */
-export type PathTuple = Key[];
-
-/**
- * Type to assert that a type is a {@link PathTuple}.
- * @typeParam T - type which may be a {@link PathTuple}
- */
-export type AsPathTuple<T> = Extract<T, PathTuple>;
-
-/**
- * Type to intersect a union type.
- * See https://fettblog.eu/typescript-union-to-intersection/
- * @typeParam U - union
- * @example
- * ```
- * UnionToIntersection<{ foo: string } | { bar: number }>
- *   = { foo: string; bar: number }
- * ```
- */
-export type UnionToIntersection<U> = (
-  U extends any ? (_: U) => any : never
-) extends (_: infer I) => any
-  ? I
-  : never;
-
-/**
- * Type which appends a {@link Key} to the {@link PathTuple} only if it is not
- * blank, i.e. not the empty string.
- * @typeParam PT - path
- * @typeParam K  - key
- * @example
- * ```
- * AppendNonBlankKey<['foo'], 'bar'> = ['foo', 'bar']
- * AppendNonBlankKey<['foo'], ''> = ['foo']
- * ```
- */
-export type AppendNonBlankKey<
-  PT extends PathTuple,
-  K extends Key,
-> = K extends '' ? PT : [...PT, K];
-
-/**
- * Type to implement {@link SplitPathString} tail recursively.
- * @typeParam PS - remaining {@link PathString} which should be split into its
- *                 individual {@link Key}s
- * @typeParam PT - accumulator of the {@link Key}s which have been split from
- *                 the original {@link PathString} already
- */
-type SplitPathStringImpl<
-  PS extends PathString,
-  PT extends PathTuple,
-> = PS extends `${infer K}.${infer R}`
-  ? SplitPathStringImpl<R, AppendNonBlankKey<PT, K>>
-  : AppendNonBlankKey<PT, PS>;
-
-/**
- * Type to split a {@link PathString} into a {@link PathTuple}.
- * The individual {@link Key}s may be empty strings.
- * @typeParam PS  - {@link PathString} which should be split into its
- *                  individual {@link Key}s
- * @example
- * ```
- * SplitPathString<'foo'> = ['foo']
- * SplitPathString<'foo.bar.0.baz'> = ['foo', 'bar', '0', 'baz']
- * SplitPathString<'.'> = []
- * ```
- */
-export type SplitPathString<PS extends PathString> = SplitPathStringImpl<
-  PS,
-  []
->;
-
-/**
- * Type to implement {@link JoinPathTuple} tail-recursively.
- * @typeParam PT - remaining {@link Key}s which needs to be joined
- * @typeParam PS - accumulator of the already joined {@link Key}s
- */
-type JoinPathTupleImpl<
-  PT extends PathTuple,
-  PS extends PathString,
-> = PT extends [infer K, ...infer R]
-  ? JoinPathTupleImpl<AsPathTuple<R>, `${PS}.${AsKey<K>}`>
-  : PS;
-
-/**
- * Type to join a {@link PathTuple} to a {@link PathString}.
- * @typeParam PT - {@link PathTuple} which should be joined.
- * @example
- * ```
- * JoinPathTuple<['foo']> = 'foo'
- * JoinPathTuple<['foo', 'bar', '0', 'baz']> = 'foo.bar.0.baz'
- * JoinPathTuple<[]> = never
- * ```
- */
-export type JoinPathTuple<PT extends PathTuple> = PT extends [
-  infer K,
-  ...infer R,
-]
-  ? JoinPathTupleImpl<AsPathTuple<R>, AsKey<K>>
-  : never;
-
-/**
- * Type which converts all keys of an object to {@link Key}s.
- * @typeParam T - object type
- * @example
- * ```
- * MapKeys<{0: string}> = {'0': string}
- * ```
- */
-type MapKeys<T> = { [K in keyof T as ToKey<K>]: T[K] };
-
-/**
- * Type to access a type by a key.
- *  - Returns undefined if it can't be indexed by that key.
- *  - Returns null if the type is null.
- *  - Returns undefined if the type is not traversable.
- * @typeParam T - type which is indexed by the key
- * @typeParam K - key into the type
- * ```
- * TryAccess<{foo: string}, 'foo'> = string
- * TryAccess<{foo: string}, 'bar'> = undefined
- * TryAccess<null, 'foo'> = null
- * TryAccess<string, 'foo'> = undefined
- * ```
- */
-type TryAccess<T, K> = K extends keyof T
-  ? T[K]
-  : T extends null
-  ? null
-  : undefined;
-
-/**
- * Type to access an array type by a key.
- * Returns undefined if the key is non-numeric.
- * @typeParam T - type which is indexed by the key
- * @typeParam K - key into the type
- * ```
- * TryAccessArray<string[], '0'> = string
- * TryAccessArray<string[], 'foo'> = undefined
- * ```
- */
-type TryAccessArray<
-  T extends ReadonlyArray<any>,
-  K extends Key,
-> = K extends `${ArrayKey}` ? T[number] : TryAccess<T, K>;
-
-/**
- * Type to evaluate the type which the given key points to.
- * @typeParam T - type which is indexed by the key
- * @typeParam K - key into the type
- * @example
- * ```
- * EvaluateKey<{foo: string}, 'foo'> = string
- * EvaluateKey<[number, string], '1'> = string
- * EvaluateKey<string[], '1'> = string
- * ```
- */
-export type EvaluateKey<T, K extends Key> = T extends ReadonlyArray<any>
-  ? IsTuple<T> extends true
-    ? TryAccess<T, K>
-    : TryAccessArray<T, K>
-  : TryAccess<MapKeys<T>, K>;
-
-/**
- * Type to evaluate the type which the given path points to.
- * @typeParam T  - deeply nested type which is indexed by the path
- * @typeParam PT - path into the deeply nested type
- * @example
- * ```
- * EvaluatePath<{foo: {bar: string}}, ['foo', 'bar']> = string
- * EvaluatePath<[number, string], ['1']> = string
- * EvaluatePath<number, []> = number
- * EvaluatePath<number, ['foo']> = undefined
- * ```
- */
-export type EvaluatePath<T, PT extends PathTuple> = PT extends [
-  infer K,
-  ...infer R,
-]
-  ? EvaluatePath<EvaluateKey<T, AsKey<K>>, AsPathTuple<R>>
-  : T;
-
-/**
- * Type which given a tuple type returns its own keys, i.e. only its indices.
- * @typeParam T - tuple type
- * @example
- * ```
- * TupleKeys<[number, string]> = '0' | '1'
- * ```
- */
-export type TupleKeys<T extends ReadonlyArray<any>> = Exclude<
-  keyof T,
-  keyof any[]
->;
-
-/**
- * Type which extracts all numeric keys from an object.
- * @typeParam T - type
- * @example
- * ```
- * NumericObjectKeys<{0: string, '1': string, foo: string}> = '0' | '1'
- * ```
- */
-type NumericObjectKeys<T extends Traversable> = ToKey<
-  Extract<keyof T, ArrayKey | `${ArrayKey}`>
->;
-
-/**
- * Type which extracts all numeric keys from an object, tuple, or array.
- * If a union is passed, it evaluates to the overlapping numeric keys.
- * @typeParam T - type
- * @example
- * ```
- * NumericKeys<{0: string, '1': string, foo: string}> = '0' | '1'
- * NumericKeys<number[]> = `${number}`
- * NumericKeys<[string, number]> = '0' | '1'
- * NumericKeys<{0: string, '1': string} | [number] | number[]> = '0'
- * ```
- */
-export type NumericKeys<T extends Traversable> = UnionToIntersection<
-  T extends ReadonlyArray<any>
-    ? IsTuple<T> extends true
-      ? [TupleKeys<T>]
-      : [ToKey<ArrayKey>]
-    : [NumericObjectKeys<T>]
->[never];
-
-/**
- * Type which extracts all keys from an object.
- * If a union is passed, it evaluates to the overlapping keys.
- * @typeParam T - object type
- * @example
- * ```
- * ObjectKeys<{foo: string, bar: string}, string> = 'foo' | 'bar'
- * ObjectKeys<{foo: string, bar: number}, string> = 'foo'
- * ```
- */
-export type ObjectKeys<T extends Traversable> = Exclude<
-  ToKey<keyof T>,
-  `${string}.${string}` | ''
->;
-
-/**
- * Type to check whether a type's property matches the constraint type
- * and return its key. Converts the key to a {@link Key}.
- * @typeParam T - type whose property should be checked
- * @typeParam K - key of the property
- * @typeParam U - constraint type
- * @example
- * ```
- * CheckKeyConstraint<{foo: string}, 'foo', string> = 'foo'
- * CheckKeyConstraint<{foo: string}, 'foo', number> = never
- * CheckKeyConstraint<string[], number, string> = `${number}`
- * ```
- */
-export type CheckKeyConstraint<T, K extends Key, U> = K extends any
-  ? EvaluateKey<T, K> extends U
-    ? K
-    : never
-  : never;
-
-/**
- * Type which evaluates to true when the type is an array or tuple or is a union
- * which contains an array or tuple.
- * @typeParam T - type
- * @example
- * ```
- * ContainsIndexable<{foo: string}> = false
- * ContainsIndexable<{foo: string} | number[]> = true
- * ```
- */
-export type ContainsIndexable<T> = IsNever<
-  Extract<T, ReadonlyArray<any>>
-> extends true
-  ? false
-  : true;
-
-/**
- * Type to implement {@link Keys} for non-nullable values.
- * @typeParam T - non-nullable type whose property should be checked
- */
-type KeysImpl<T> = [T] extends [Traversable]
-  ? ContainsIndexable<T> extends true
-    ? NumericKeys<T>
-    : ObjectKeys<T>
-  : never;
-
-/**
- * Type to find all properties of a type that match the constraint type
- * and return their keys.
- * If a union is passed, it evaluates to the overlapping keys.
- * @typeParam T - type whose property should be checked
- * @typeParam U - constraint type
- * @example
- * ```
- * Keys<{foo: string, bar: string}, string> = 'foo' | 'bar'
- * Keys<{foo?: string, bar?: string}> = 'foo' | 'bar'
- * Keys<{foo: string, bar: number}, string> = 'foo'
- * Keys<[string, number], string> = '0'
- * Keys<string[], string> = `${number}`
- * Keys<{0: string, '1': string} | [number] | number[]> = '0'
- * ```
- */
-export type Keys<T, U = unknown> = IsAny<T> extends true
-  ? Key
-  : IsNever<T> extends true
-  ? Key
-  : IsNever<NonNullable<T>> extends true
-  ? never
-  : CheckKeyConstraint<T, KeysImpl<NonNullable<T>>, U>;
-
-/**
- * Type to check whether a {@link Key} is present in a type.
- * If a union of {@link Key}s is passed, all {@link Key}s have to be present
- * in the type.
- * @typeParam T - type which is introspected
- * @typeParam K - key
- * @example
- * ```
- * HasKey<{foo: string}, 'foo'> = true
- * HasKey<{foo: string}, 'bar'> = false
- * HasKey<{foo: string}, 'foo' | 'bar'> = false
- * ```
- */
-export type HasKey<T, K extends Key> = IsNever<Exclude<K, Keys<T>>>;
-
-/**
- * Type to implement {@link ValidPathPrefix} tail recursively.
- * @typeParam T   - type which the path should be checked against
- * @typeParam PT  - path which should exist within the given type
- * @typeParam VPT - accumulates the prefix of {@link Key}s which have been
- *                  confirmed to exist already
- */
-type ValidPathPrefixImpl<
-  T,
-  PT extends PathTuple,
-  VPT extends PathTuple,
-> = PT extends [infer K, ...infer R]
-  ? HasKey<T, AsKey<K>> extends true
-    ? ValidPathPrefixImpl<
-        EvaluateKey<T, AsKey<K>>,
-        AsPathTuple<R>,
-        AsPathTuple<[...VPT, K]>
-      >
-    : VPT
-  : VPT;
-
-/**
- * Type to find the longest path prefix which is still valid,
- * i.e. exists within the given type.
- * @typeParam T  - type which the path should be checked against
- * @typeParam PT - path which should exist within the given type
- * @example
- * ```
- * ValidPathPrefix<{foo: {bar: string}}, ['foo', 'bar']> = ['foo', 'bar']
- * ValidPathPrefix<{foo: {bar: string}}, ['foo', 'ba']> = ['foo']
- * ```
- */
-export type ValidPathPrefix<T, PT extends PathTuple> = ValidPathPrefixImpl<
-  T,
-  PT,
-  []
->;
-
-/**
- * Type to check whether a path through a type exists.
- * @typeParam T  - type which the path should be checked against
- * @typeParam PT - path which should exist within the given type
- * @example
- * ```
- * HasPath<{foo: {bar: string}}, ['foo', 'bar']> = true
- * HasPath<{foo: {bar: string}}, ['foo', 'ba']> = false
- * ```
- */
-export type HasPath<T, PT extends PathTuple> = ValidPathPrefix<T, PT> extends PT
-  ? true
-  : false;
-
-/**
- * Helper function to break apart T1 and check if any are equal to T2
- *
- * See {@link IsEqual}
- */
-type AnyIsEqual<T1, T2> = T1 extends T2
-  ? IsEqual<T1, T2> extends true
-    ? true
-    : never
-  : never;
-
-type HttpMethod = 'get' | 'post' | 'put' | 'delete' | 'all';
-
-/**
- * Helper type for recursively constructing paths through a type.
- * This actually constructs the strings and recurses into nested
- * object types.
- *
- * See {@link Path}
- */
-type PathImpl<K extends string | number, V, TraversedTypes> = V extends
-  | Primitive
-  | BrowserNativeObject
-  ? `${K}`
-  : // Check so that we don't recurse into the same type
-  // by ensuring that the types are mutually assignable
-  // mutually required to avoid false positives of subtypes
-  true extends AnyIsEqual<TraversedTypes, V>
-  ? `${K}`
-  : true extends AnyIsEqual<HttpMethod, K>
-  ? ``
-  : `${K}` | `${K}.${PathInternal<V, TraversedTypes | V>}`;
-
-/**
- * Helper type for recursively constructing paths through a type.
- * This obsucres the internal type param TraversedTypes from exported contract.
- *
- * See {@link Path}
- */
-type PathInternal<T, TraversedTypes = T> = T extends ReadonlyArray<infer V>
-  ? IsTuple<T> extends true
-    ? {
-        [K in TupleKeys<T>]-?: PathImpl<K & string, T[K], TraversedTypes>;
-      }[TupleKeys<T>]
-    : PathImpl<ArrayKey, V, TraversedTypes>
-  : {
-      [K in keyof T]-?: PathImpl<K & string, T[K], TraversedTypes>;
-    }[keyof T];
-
-/**
- * Type which eagerly collects all paths through a type
- * @typeParam T - type which should be introspected
- * @example
- * ```
- * Path<{foo: {bar: string}}> = 'foo' | 'foo.bar'
- * ```
- */
-// We want to explode the union type and process each individually
-// so assignable types don't leak onto the stack from the base.
-export type Path<T> = T extends any ? PathInternal<T> : never;
-
-/**
- * See {@link Path}
- */
-export type FieldPath<TFieldValues extends FieldValues> = Path<TFieldValues>;
-
-/**
- * Helper type for recursively constructing paths through a type.
- * This actually constructs the strings and recurses into nested
- * object types.
- *
- * See {@link ArrayPath}
- */
-type ArrayPathImpl<K extends string | number, V, TraversedTypes> = V extends
-  | Primitive
-  | BrowserNativeObject
-  ? IsAny<V> extends true
-    ? string
-    : never
-  : V extends ReadonlyArray<infer U>
-  ? U extends Primitive | BrowserNativeObject
-    ? IsAny<V> extends true
-      ? string
-      : never
-    : // Check so that we don't recurse into the same type
-    // by ensuring that the types are mutually assignable
-    // mutually required to avoid false positives of subtypes
-    true extends AnyIsEqual<TraversedTypes, V>
-    ? never
-    : `${K}` | `${K}.${ArrayPathInternal<V, TraversedTypes | V>}`
-  : true extends AnyIsEqual<TraversedTypes, V>
-  ? never
-  : `${K}.${ArrayPathInternal<V, TraversedTypes | V>}`;
-
-/**
- * Helper type for recursively constructing paths through a type.
- * This obsucres the internal type param TraversedTypes from exported contract.
- *
- * See {@link ArrayPath}
- */
-type ArrayPathInternal<T, TraversedTypes = T> = T extends ReadonlyArray<infer V>
-  ? IsTuple<T> extends true
-    ? {
-        [K in TupleKeys<T>]-?: ArrayPathImpl<K & string, T[K], TraversedTypes>;
-      }[TupleKeys<T>]
-    : ArrayPathImpl<ArrayKey, V, TraversedTypes>
-  : {
-      [K in keyof T]-?: ArrayPathImpl<K & string, T[K], TraversedTypes>;
-    }[keyof T];
-
-/**
- * Type which eagerly collects all paths through a type which point to an array
- * type.
- * @typeParam T - type which should be introspected.
- * @example
- * ```
- * Path<{foo: {bar: string[], baz: number[]}}> = 'foo.bar' | 'foo.baz'
- * ```
- */
-// We want to explode the union type and process each individually
-// so assignable types don't leak onto the stack from the base.
-export type ArrayPath<T> = T extends any ? ArrayPathInternal<T> : never;
-
-/**
- * See {@link ArrayPath}
- */
-export type FieldArrayPath<TFieldValues extends FieldValues> =
-  ArrayPath<TFieldValues>;
-
-/**
- * Type to evaluate the type which the given path points to.
- * @typeParam T - deeply nested type which is indexed by the path
- * @typeParam P - path into the deeply nested type
- * @example
- * ```
- * PathValue<{foo: {bar: string}}, 'foo.bar'> = string
- * PathValue<[number, string], '1'> = string
- * ```
- */
-export type PathValue<T, P extends Path<T> | ArrayPath<T>> = T extends any
-  ? P extends `${infer K}.${infer R}`
-    ? K extends keyof T
-      ? R extends Path<T[K]>
-        ? PathValue<T[K], R>
-        : never
-      : K extends `${ArrayKey}`
-      ? T extends ReadonlyArray<infer V>
-        ? PathValue<V, R & Path<V>>
-        : never
-      : never
-    : P extends keyof T
-    ? T[P]
-    : P extends `${ArrayKey}`
-    ? T extends ReadonlyArray<infer V>
-      ? V
-      : never
-    : never
-  : never;
-
-/**
- * See {@link PathValue}
- */
-export type FieldPathValue<
-  TFieldValues extends FieldValues,
-  TFieldPath extends FieldPath<TFieldValues>,
-> = PathValue<TFieldValues, TFieldPath>;
-
-/**
- * See {@link PathValue}
- */
-export type FieldArrayPathValue<
-  TFieldValues extends FieldValues,
-  TFieldArrayPath extends FieldArrayPath<TFieldValues>,
-> = PathValue<TFieldValues, TFieldArrayPath>;
-
-/**
- * Type to evaluate the type which the given paths point to.
- * @typeParam TFieldValues - field values which are indexed by the paths
- * @typeParam TPath        - paths into the deeply nested field values
- * @example
- * ```
- * FieldPathValues<{foo: {bar: string}}, ['foo', 'foo.bar']>
- *   = [{bar: string}, string]
- * ```
- */
-export type FieldPathValues<
-  TFieldValues extends FieldValues,
-  TPath extends FieldPath<TFieldValues>[] | readonly FieldPath<TFieldValues>[],
-> = {} & {
-  [K in keyof TPath]: FieldPathValue<
-    TFieldValues,
-    TPath[K] & FieldPath<TFieldValues>
-  >;
-};
-
-/**
- * Type which eagerly collects all paths through a fieldType that matches a give type
- * @typeParam TFieldValues - field values which are indexed by the paths
- * @typeParam TValue       - the value you want to match into each type
- * @example
- * ```typescript
- * FieldPathByValue<{foo: {bar: number}, baz: number, bar: string}, number>
- *   = 'foo.bar' | 'baz'
- * ```
- */
-export type FieldPathByValue<TFieldValues extends FieldValues, TValue> = {
-  [FieldKey in FieldPath<TFieldValues>]: FieldPathValue<
-    TFieldValues,
-    FieldKey
-  > extends TValue
-    ? FieldKey
-    : never;
-}[FieldPath<TFieldValues>];
diff --git a/plugins/openapi-router-common/src/types/requests.ts b/plugins/openapi-router-common/src/types/requests.ts
new file mode 100644
index 0000000000..49f30d0e94
--- /dev/null
+++ b/plugins/openapi-router-common/src/types/requests.ts
@@ -0,0 +1,36 @@
+/**
+ * Pulled from https://github.com/varanauskas/oatx.
+ */
+import type { ReferenceObject, RequestBodyObject } from 'openapi3-ts';
+import type {
+  ComponentRef,
+  ComponentTypes,
+  ObjectWithContentSchema,
+  RequiredDoc,
+  DocOperation,
+  DocPath,
+  DocPathMethod,
+  DocPathTemplate,
+} from './common';
+
+type RequestBody<
+  Doc extends RequiredDoc,
+  Path extends Extract<keyof Doc['paths'], string>,
+  Method extends keyof Doc['paths'][Path],
+> = DocOperation<Doc, Path, Method>['requestBody'] extends ReferenceObject
+  ? 'requestBodies' extends ComponentTypes<Doc>
+    ? ComponentRef<
+        Doc,
+        'requestBodies',
+        DocOperation<Doc, Path, Method>['requestBody']
+      >
+    : never
+  : DocOperation<Doc, Path, Method>['requestBody'];
+
+export type RequestBodySchema<
+  Doc extends RequiredDoc,
+  Path extends DocPathTemplate<Doc>,
+  Method extends DocPathMethod<Doc, Path>,
+> = RequestBody<Doc, DocPath<Doc, Path>, Method> extends RequestBodyObject
+  ? ObjectWithContentSchema<Doc, RequestBody<Doc, DocPath<Doc, Path>, Method>>
+  : never;
diff --git a/plugins/openapi-router-common/src/types/response.ts b/plugins/openapi-router-common/src/types/response.ts
new file mode 100644
index 0000000000..f4b2f0d92d
--- /dev/null
+++ b/plugins/openapi-router-common/src/types/response.ts
@@ -0,0 +1,68 @@
+/**
+ * Pulled from https://github.com/varanauskas/oatx.
+ */
+import type { ReferenceObject, ResponseObject } from 'openapi3-ts';
+import type {
+  ComponentRef,
+  ComponentTypes,
+  ObjectWithContentSchema,
+  RequiredDoc,
+  DocOperation,
+  DocPath,
+  DocPathMethod,
+  DocPathTemplate,
+} from './common';
+
+type Response<
+  Doc extends RequiredDoc,
+  Path extends keyof Doc['paths'],
+  Method extends keyof Doc['paths'][Path],
+  StatusCode extends keyof Doc['paths'][Path]['responses'],
+> = DocOperation<
+  Doc,
+  Path,
+  Method
+>['responses'][StatusCode] extends ReferenceObject
+  ? 'responses' extends ComponentTypes<Doc>
+    ? ComponentRef<
+        Doc,
+        'responses',
+        DocOperation<Doc, Path, Method>['responses'][StatusCode]
+      >
+    : never
+  : DocOperation<Doc, Path, Method>['responses'][StatusCode];
+
+type Responses<
+  Doc extends RequiredDoc,
+  Path extends keyof Doc['paths'],
+  Method extends keyof Doc['paths'][Path],
+> = {
+  [StatusCode in keyof DocOperation<Doc, Path, Method>['responses']]: Response<
+    Doc,
+    Path,
+    Method,
+    StatusCode
+  >;
+};
+
+export type ResponseSchema<
+  Doc extends RequiredDoc,
+  Object extends ResponseObject,
+> = ObjectWithContentSchema<Doc, Object>;
+
+export type ResponseSchemas<
+  Doc extends RequiredDoc,
+  Path extends DocPathTemplate<Doc>,
+  Method extends DocPathMethod<Doc, Path>,
+> = {
+  [StatusCode in keyof Responses<Doc, DocPath<Doc, Path>, Method>]: Responses<
+    Doc,
+    DocPath<Doc, Path>,
+    Method
+  >[StatusCode] extends ResponseObject
+    ? ResponseSchema<
+        Doc,
+        Responses<Doc, DocPath<Doc, Path>, Method>[StatusCode]
+      >
+    : never;
+};
diff --git a/plugins/openapi-router-common/src/types/utils.ts b/plugins/openapi-router-common/src/types/utils.ts
deleted file mode 100644
index 25282e1da2..0000000000
--- a/plugins/openapi-router-common/src/types/utils.ts
+++ /dev/null
@@ -1,144 +0,0 @@
-/*
- * Copyright 2023 The Backstage Authors
- *
- * Licensed under the Apache License, Version 2.0 (the "License");
- * you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- *     http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
- */
-declare const $NestedValue: unique symbol;
-
-/**
- * @deprecated to be removed in the next major version
- */
-export type NestedValue<TValue extends object = object> = {
-  [$NestedValue]: never;
-} & TValue;
-
-/*
-Projects that React Hook Form installed don't include the DOM library need these interfaces to compile.
-React Native applications is no DOM available. The JavaScript runtime is ES6/ES2015 only.
-These definitions allow such projects to compile with only --lib ES6.
-
-Warning: all of these interfaces are empty.
-If you want type definitions for various properties, you need to add `--lib DOM` (via command line or tsconfig.json).
-*/
-
-export type Noop = () => void;
-
-interface File extends Blob {
-  readonly lastModified: number;
-  readonly name: string;
-}
-
-interface FileList {
-  readonly length: number;
-  item(index: number): File | null;
-  [index: number]: File;
-}
-
-export type Primitive =
-  | null
-  | undefined
-  | string
-  | number
-  | boolean
-  | symbol
-  | bigint;
-
-export type BrowserNativeObject = Date | FileList | File;
-
-export type EmptyObject = { [K in string | number]: never };
-
-export type NonUndefined<T> = T extends undefined ? never : T;
-
-export type LiteralUnion<T extends U, U extends Primitive> =
-  | T
-  | (U & { _?: never });
-
-export type DeepPartial<T> = T extends BrowserNativeObject | NestedValue
-  ? T
-  : { [K in keyof T]?: DeepPartial<T[K]> };
-
-export type DeepPartialSkipArrayKey<T> = T extends
-  | BrowserNativeObject
-  | NestedValue
-  ? T
-  : T extends ReadonlyArray<any>
-  ? { [K in keyof T]: DeepPartialSkipArrayKey<T[K]> }
-  : { [K in keyof T]?: DeepPartialSkipArrayKey<T[K]> };
-
-/**
- * Checks whether the type is any
- * See {@link https://stackoverflow.com/a/49928360/3406963}
- * @typeParam T - type which may be any
- * ```
- * IsAny<any> = true
- * IsAny<string> = false
- * ```
- */
-export type IsAny<T> = 0 extends 1 & T ? true : false;
-
-/**
- * Checks whether the type is never
- * @typeParam T - type which may be never
- * ```
- * IsAny<never> = true
- * IsAny<string> = false
- * ```
- */
-export type IsNever<T> = [T] extends [never] ? true : false;
-
-/**
- * Checks whether T1 can be exactly (mutually) assigned to T2
- * @typeParam T1 - type to check
- * @typeParam T2 - type to check against
- * ```
- * IsEqual<string, string> = true
- * IsEqual<'foo', 'foo'> = true
- * IsEqual<string, number> = false
- * IsEqual<string, number> = false
- * IsEqual<string, 'foo'> = false
- * IsEqual<'foo', string> = false
- * IsEqual<'foo' | 'bar', 'foo'> = boolean // 'foo' is assignable, but 'bar' is not (true | false) -> boolean
- * ```
- */
-export type IsEqual<T1, T2> = T1 extends T2
-  ? (<G>() => G extends T1 ? 1 : 2) extends <G>() => G extends T2 ? 1 : 2
-    ? true
-    : false
-  : false;
-
-export type DeepMap<T, TValue> = IsAny<T> extends true
-  ? any
-  : T extends BrowserNativeObject | NestedValue
-  ? TValue
-  : T extends object
-  ? { [K in keyof T]: DeepMap<NonUndefined<T[K]>, TValue> }
-  : TValue;
-
-export type IsFlatObject<T extends object> = Extract<
-  Exclude<T[keyof T], NestedValue | Date | FileList>,
-  any[] | object
-> extends never
-  ? true
-  : false;
-
-export type Merge<A, B> = {
-  [K in keyof A | keyof B]?: K extends keyof A & keyof B
-    ? [A[K], B[K]] extends [object, object]
-      ? Merge<A[K], B[K]>
-      : A[K] | B[K]
-    : K extends keyof A
-    ? A[K]
-    : K extends keyof B
-    ? B[K]
-    : never;
-};
diff --git a/yarn.lock b/yarn.lock
index eb39765348..0396822f80 100644
--- a/yarn.lock
+++ b/yarn.lock
@@ -7454,6 +7454,8 @@ __metadata:
     express: ^4.18.2
     json-schema-to-ts: ^2.6.2
     openapi-types: ^12.1.0
+    openapi3-ts: ^3.1.2
+    ts-node: ^10.9.1
   languageName: unknown
   linkType: soft
 
@@ -32110,6 +32112,15 @@ __metadata:
   languageName: node
   linkType: hard
 
+"openapi3-ts@npm:^3.1.2":
+  version: 3.1.2
+  resolution: "openapi3-ts@npm:3.1.2"
+  dependencies:
+    yaml: ^2.1.3
+  checksum: 77e5064ea9bff119ba8d8398a90246ae99174d6c23b2ed68355bb48be3243b6f4f0041a3fdcd9dba5ffe6ace786a8041d86d8a4049d65d2d40cd4bfca5bba459
+  languageName: node
+  linkType: hard
+
 "openid-client@npm:^5.2.1, openid-client@npm:^5.3.0":
   version: 5.4.0
   resolution: "openid-client@npm:5.4.0"

From eaefab31c630ddee1570a0ca92aae0af499331b2 Mon Sep 17 00:00:00 2001
From: Aramis Sennyey <sennyeya@amazon.com>
Date: Thu, 16 Feb 2023 16:32:53 -0500
Subject: [PATCH 05/61] Update catalog-backend to use custom router.

Signed-off-by: Aramis Sennyey <sennyeya@amazon.com>
---
 plugins/catalog-backend/package.json          |    1 +
 .../src/service/createRouter.ts               |  297 ++---
 .../src/service/schema/openapi.ts             | 1079 +++++++++++++++++
 plugins/openapi-router-common/package.json    |    4 +-
 plugins/openapi-router-common/src/router.ts   |   25 +-
 .../openapi-router-common/src/types/common.ts |   16 +
 .../openapi-router-common/src/types/index.ts  |   15 +
 .../src/types/requests.ts                     |   17 +
 .../src/types/response.ts                     |   17 +
 yarn.lock                                     |    7 +-
 10 files changed, 1298 insertions(+), 180 deletions(-)
 create mode 100644 plugins/catalog-backend/src/service/schema/openapi.ts

diff --git a/plugins/catalog-backend/package.json b/plugins/catalog-backend/package.json
index 65a3232e69..df5560459b 100644
--- a/plugins/catalog-backend/package.json
+++ b/plugins/catalog-backend/package.json
@@ -54,6 +54,7 @@
     "@backstage/integration": "workspace:^",
     "@backstage/plugin-catalog-common": "workspace:^",
     "@backstage/plugin-catalog-node": "workspace:^",
+    "@backstage/plugin-openapi-router": "workspace:^",
     "@backstage/plugin-permission-common": "workspace:^",
     "@backstage/plugin-permission-node": "workspace:^",
     "@backstage/plugin-scaffolder-common": "workspace:^",
diff --git a/plugins/catalog-backend/src/service/createRouter.ts b/plugins/catalog-backend/src/service/createRouter.ts
index f6c2e441e5..19535bfec7 100644
--- a/plugins/catalog-backend/src/service/createRouter.ts
+++ b/plugins/catalog-backend/src/service/createRouter.ts
@@ -23,9 +23,8 @@ import {
   stringifyEntityRef,
 } from '@backstage/catalog-model';
 import { Config } from '@backstage/config';
-import { InputError, NotFoundError, serializeError } from '@backstage/errors';
+import { NotFoundError, serializeError } from '@backstage/errors';
 import express from 'express';
-import Router from 'express-promise-router';
 import { Logger } from 'winston';
 import yn from 'yn';
 import { z } from 'zod';
@@ -50,16 +49,8 @@ import {
   locationInput,
   validateRequestBody,
 } from './util';
-import { initialize } from 'express-openapi';
-import yaml from 'js-yaml';
-import fs from 'fs';
-import path from 'path';
-
-class ParsingError extends Error {
-  toString() {
-    return `ParsingError: ${this.message}`;
-  }
-}
+import { ApiRouter, DeepWriteable } from '@backstage/plugin-openapi-router';
+import spec from './schema/openapi';
 
 /**
  * Options used by {@link createRouter}.
@@ -95,7 +86,9 @@ export async function createRouter(
     logger,
     permissionIntegrationRouter,
   } = options;
-  const router = Router();
+  const router = new ApiRouter<DeepWriteable<typeof spec>>(
+    spec as DeepWriteable<typeof spec>,
+  );
   router.use(express.json());
 
   const readonlyEnabled =
@@ -104,42 +97,26 @@ export async function createRouter(
     logger.info('Catalog is running in readonly mode');
   }
 
-  const validateDependency = (
-    dependency: any,
-    next: (req: express.Request, res: express.Response) => any,
-  ) => {
-    return (req: express.Request, res: express.Response) => {
-      if (!dependency) {
-        console.log('no dependency');
-        throw new NotFoundError(
-          'Dependency Error',
-          'Dependency not set up for this endpoint.',
-        );
-      }
-      return next(req, res);
-    };
-  };
+  if (refreshService) {
+    router.post('/refresh', async (req, res) => {
+      const refreshOptions: RefreshOptions = req.body;
+      refreshOptions.authorizationToken = getBearerToken(
+        req.header('authorization'),
+      );
 
-  initialize({
-    app: router as any,
-    // NOTE: If using yaml you can provide a path relative to process.cwd() e.g.
-    // apiDoc: './api-v1/api-doc.yml',
-    apiDoc: yaml.load(
-      // eslint-disable-next-line no-restricted-syntax
-      fs.readFileSync(path.resolve(__dirname, '../../openapi.yaml'), 'utf-8'),
-    ) as any,
-    operations: {
-      RefreshEntity: validateDependency(refreshService, async (req, res) => {
-        const refreshOptions: RefreshOptions = req.body;
-        refreshOptions.authorizationToken = getBearerToken(
-          req.header('authorization'),
-        );
+      await refreshService.refresh(refreshOptions);
+      res.status(200).end();
+    });
+  }
 
-        await refreshService!.refresh(refreshOptions);
-        res.status(200).end();
-      }),
-      GetEntities: validateDependency(entitiesCatalog, async (req, res) => {
-        const { entities, pageInfo } = await entitiesCatalog!.entities({
+  if (permissionIntegrationRouter) {
+    router.use(permissionIntegrationRouter);
+  }
+
+  if (entitiesCatalog) {
+    router
+      .get('/entities', async (req, res) => {
+        const { entities, pageInfo } = await entitiesCatalog.entities({
           filter: parseEntityFilterParams(req.query),
           fields: parseEntityTransformParams(req.query),
           order: parseEntityOrderParams(req.query),
@@ -157,10 +134,10 @@ export async function createRouter(
 
         // TODO(freben): encode the pageInfo in the response
         res.json(entities);
-      }),
-      GetEntityByUid: validateDependency(entitiesCatalog, async (req, res) => {
+      })
+      .get('/entities/by-uid/:uid', async (req, res) => {
         const { uid } = req.params;
-        const { entities } = await entitiesCatalog!.entities({
+        const { entities } = await entitiesCatalog.entities({
           filter: basicEntityFilter({ 'metadata.uid': uid }),
           authorizationToken: getBearerToken(req.header('authorization')),
         });
@@ -168,10 +145,17 @@ export async function createRouter(
           throw new NotFoundError(`No entity with uid ${uid}`);
         }
         res.status(200).json(entities[0]);
-      }),
-      GetEntityByName: validateDependency(entitiesCatalog, async (req, res) => {
+      })
+      .delete('/entities/by-uid/:uid', async (req, res) => {
+        const { uid } = req.params;
+        await entitiesCatalog.removeEntityByUid(uid, {
+          authorizationToken: getBearerToken(req.header('authorization')),
+        });
+        res.status(204).end();
+      })
+      .get('/entities/by-name/:kind/:namespace/:name', async (req, res) => {
         const { kind, namespace, name } = req.params;
-        const { entities } = await entitiesCatalog!.entities({
+        const { entities } = await entitiesCatalog.entities({
           filter: basicEntityFilter({
             kind: kind,
             'metadata.namespace': namespace,
@@ -185,27 +169,41 @@ export async function createRouter(
           );
         }
         res.status(200).json(entities[0]);
-      }),
-      GetEntityAncestryByName: validateDependency(
-        entitiesCatalog,
+      })
+      .get(
+        '/entities/by-name/:kind/:namespace/:name/ancestry',
         async (req, res) => {
           const { kind, namespace, name } = req.params;
           const entityRef = stringifyEntityRef({ kind, namespace, name });
-          const response = await entitiesCatalog!.entityAncestry(entityRef, {
+          const response = await entitiesCatalog.entityAncestry(entityRef, {
             authorizationToken: getBearerToken(req.header('authorization')),
           });
           res.status(200).json(response);
         },
-      ),
-      GetEntityFacets: validateDependency(entitiesCatalog, async (req, res) => {
-        const response = await entitiesCatalog!.facets({
+      )
+      .post('/entities/by-refs', async (req, res) => {
+        const request = entitiesBatchRequest(req);
+        const token = getBearerToken(req.header('authorization'));
+        const response = await entitiesCatalog.entitiesBatch({
+          entityRefs: request.entityRefs,
+          fields: parseEntityTransformParams(req.query, request.fields),
+          authorizationToken: token,
+        });
+        res.status(200).json(response);
+      })
+      .get('/entity-facets', async (req, res) => {
+        const response = await entitiesCatalog.facets({
           filter: parseEntityFilterParams(req.query),
           facets: parseEntityFacetParams(req.query),
           authorizationToken: getBearerToken(req.header('authorization')),
         });
         res.status(200).json(response);
-      }),
-      CreateLocation: validateDependency(locationService, async (req, res) => {
+      });
+  }
+
+  if (locationService) {
+    router
+      .post('/locations', async (req, res) => {
         const location = await validateRequestBody(req, locationInput);
         const dryRun = yn(req.query.dryRun, { default: false });
 
@@ -219,21 +217,22 @@ export async function createRouter(
           authorizationToken: getBearerToken(req.header('authorization')),
         });
         res.status(201).json(output);
-      }),
-      GetLocations: validateDependency(locationService, async (req, res) => {
+      })
+      .get('/locations', async (req, res) => {
         const locations = await locationService.listLocations({
           authorizationToken: getBearerToken(req.header('authorization')),
         });
         res.status(200).json(locations.map(l => ({ data: l })));
-      }),
-      GetLocation: validateDependency(locationService, async (req, res) => {
+      })
+
+      .get('/locations/:id', async (req, res) => {
         const { id } = req.params;
         const output = await locationService.getLocation(id, {
           authorizationToken: getBearerToken(req.header('authorization')),
         });
         res.status(200).json(output);
-      }),
-      DeleteLocation: validateDependency(locationService, async (req, res) => {
+      })
+      .delete('/locations/:id', async (req, res) => {
         disallowReadonlyMode(readonlyEnabled);
 
         const { id } = req.params;
@@ -241,115 +240,75 @@ export async function createRouter(
           authorizationToken: getBearerToken(req.header('authorization')),
         });
         res.status(204).end();
-      }),
-      AnalyzeLocation: validateDependency(locationService, async (req, res) => {
-        const body = await validateRequestBody(
-          req,
-          z.object({
-            location: locationInput,
-            catalogFilename: z.string().optional(),
-          }),
-        );
-        const schema = z.object({
+      });
+  }
+
+  if (locationAnalyzer) {
+    router.post('/analyze-location', async (req, res) => {
+      const body = await validateRequestBody(
+        req,
+        z.object({
           location: locationInput,
           catalogFilename: z.string().optional(),
-        });
-        const output = await locationAnalyzer!.analyzeLocation(
-          schema.parse(body),
-        );
-        res.status(200).json(output);
-      }),
-      ValidateEntity: validateDependency(orchestrator, async (req, res) => {
-        const bodySchema = z.object({
-          entity: z.unknown(),
-          location: z.string(),
-        });
+        }),
+      );
+      const schema = z.object({
+        location: locationInput,
+        catalogFilename: z.string().optional(),
+      });
+      const output = await locationAnalyzer.analyzeLocation(schema.parse(body));
+      res.status(200).json(output);
+    });
+  }
 
-        let body: z.infer<typeof bodySchema>;
-        let entity: Entity;
-        let location: { type: string; target: string };
-        try {
-          body = await validateRequestBody(req, bodySchema);
-          entity = validateEntityEnvelope(body.entity);
-          location = parseLocationRef(body.location);
-          if (location.type !== 'url')
-            throw new TypeError(
-              `Invalid location ref ${body.location}, only 'url:<target>' is supported, e.g. url:https://host/path`,
-            );
-        } catch (err) {
-          return res.status(400).json({
-            errors: [serializeError(err)],
-          });
-        }
+  if (orchestrator) {
+    router.post('/validate-entity', async (req, res) => {
+      const bodySchema = z.object({
+        entity: z.unknown(),
+        location: z.string(),
+      });
 
-        const processingResult = await orchestrator!.process({
-          entity: {
-            ...entity,
-            metadata: {
-              ...entity.metadata,
-              annotations: {
-                [ANNOTATION_LOCATION]: body.location,
-                [ANNOTATION_ORIGIN_LOCATION]: body.location,
-                ...entity.metadata.annotations,
-              },
+      let body: z.infer<typeof bodySchema>;
+      let entity: Entity;
+      let location: { type: string; target: string };
+      try {
+        body = await validateRequestBody(req, bodySchema);
+        entity = validateEntityEnvelope(body.entity);
+        location = parseLocationRef(body.location);
+        if (location.type !== 'url')
+          throw new TypeError(
+            `Invalid location ref ${body.location}, only 'url:<target>' is supported, e.g. url:https://host/path`,
+          );
+      } catch (err) {
+        return res.status(400).json({
+          errors: [serializeError(err)],
+        });
+      }
+
+      const processingResult = await orchestrator.process({
+        entity: {
+          ...entity,
+          metadata: {
+            ...entity.metadata,
+            annotations: {
+              [ANNOTATION_LOCATION]: body.location,
+              [ANNOTATION_ORIGIN_LOCATION]: body.location,
+              ...entity.metadata.annotations,
             },
           },
+        },
+      });
+
+      if (!processingResult.ok)
+        res.status(400).json({
+          errors: processingResult.errors.map(e => serializeError(e)),
         });
-
-        if (!processingResult.ok)
-          res.status(400).json({
-            errors: processingResult.errors.map(e => serializeError(e)),
-          });
-        return res.status(200).end();
-      }),
-      DeleteEntityByUid: validateDependency(
-        entitiesCatalog,
-        async (req, res) => {
-          const { uid } = req.params;
-          await entitiesCatalog!.removeEntityByUid(uid, {
-            authorizationToken: getBearerToken(req.header('authorization')),
-          });
-          res.status(204).end();
-        },
-      ),
-      GetEntitiesByRefs: validateDependency(
-        entitiesCatalog,
-        async (req, res) => {
-          const request = entitiesBatchRequest(req);
-          const token = getBearerToken(req.header('authorization'));
-          const response = await entitiesCatalog!.entitiesBatch({
-            entityRefs: request.entityRefs,
-            fields: parseEntityTransformParams(req.query, request.fields),
-            authorizationToken: token,
-          });
-          res.status(200).json(response);
-        },
-      ),
-    },
-    enableObjectCoercion: true,
-    errorMiddleware: errorHandler(),
-    errorTransformer: openapiError => {
-      const error = openapiError as {
-        errorCode: string;
-        path: string;
-        message: string;
-      };
-      // eslint-disable-next-line default-case
-      switch (error.errorCode) {
-        case 'type.openapi.requestValidation':
-          throw new InputError(
-            `Invalid field ${error.path}`,
-            new ParsingError(error.message),
-          );
-      }
-      return {};
-    },
-  });
-
-  if (permissionIntegrationRouter) {
-    router.use(permissionIntegrationRouter);
+      return res.status(200).end();
+    });
   }
-  return router;
+
+  router.use(errorHandler());
+  return router.build();
 }
 
 function getBearerToken(
diff --git a/plugins/catalog-backend/src/service/schema/openapi.ts b/plugins/catalog-backend/src/service/schema/openapi.ts
new file mode 100644
index 0000000000..a8f78a36ec
--- /dev/null
+++ b/plugins/catalog-backend/src/service/schema/openapi.ts
@@ -0,0 +1,1079 @@
+/*
+ * Copyright 2023 The Backstage Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+export default {
+  openapi: '3.1.0',
+  info: {
+    title: '@backstage/plugin-catalog-backend',
+    version: '1',
+    description:
+      'The Backstage backend plugin that provides the Backstage catalog',
+    license: {
+      name: 'Apache-2.0',
+    },
+    contact: {},
+  },
+  servers: [
+    {
+      url: '/',
+    },
+  ],
+  components: {
+    examples: {},
+    headers: {},
+    parameters: {},
+    requestBodies: {},
+    responses: {},
+    schemas: {
+      RefreshOptions: {
+        type: 'object',
+        properties: {
+          authorizationToken: {
+            type: 'string',
+          },
+          entityRef: {
+            type: 'string',
+            description:
+              'The reference to a single entity that should be refreshed',
+          },
+        },
+        required: ['entityRef'],
+        description:
+          'Options for requesting a refresh of entities in the catalog.',
+      },
+      JsonObject: {
+        type: 'object',
+        properties: {},
+        description: 'A type representing all allowed JSON object values.',
+      },
+      MapStringString: {
+        type: 'object',
+        properties: {},
+        additionalProperties: {
+          type: 'string',
+        },
+        description: 'Construct a type with a set of properties K of type T',
+      },
+      EntityLink: {
+        type: 'object',
+        properties: {
+          type: {
+            type: 'string',
+            description:
+              'An optional value to categorize links into specific groups',
+          },
+          icon: {
+            type: 'string',
+            description:
+              'An optional semantic key that represents a visual icon.',
+          },
+          title: {
+            type: 'string',
+            description: 'An optional descriptive title for the link.',
+          },
+          url: {
+            type: 'string',
+            description: 'The url to the external site, document, etc.',
+          },
+        },
+        required: ['url'],
+        description:
+          'A link to external information that is related to the entity.',
+      },
+      EntityMeta: {
+        allOf: [
+          {
+            $ref: '#/components/schemas/JsonObject',
+          },
+          {
+            type: 'object',
+            properties: {
+              links: {
+                type: 'array',
+                items: {
+                  $ref: '#/components/schemas/EntityLink',
+                },
+                description:
+                  'A list of external hyperlinks related to the entity.',
+              },
+              tags: {
+                type: 'array',
+                items: {
+                  type: 'string',
+                },
+                description:
+                  'A list of single-valued strings, to for example classify catalog entities in\nvarious ways.',
+              },
+              annotations: {
+                $ref: '#/components/schemas/MapStringString',
+              },
+              labels: {
+                $ref: '#/components/schemas/MapStringString',
+              },
+              description: {
+                type: 'string',
+                description:
+                  'A short (typically relatively few words, on one line) description of the\nentity.',
+              },
+              title: {
+                type: 'string',
+                description:
+                  'A display name of the entity, to be presented in user interfaces instead\nof the `name` property above, when available.\nThis field is sometimes useful when the `name` is cumbersome or ends up\nbeing perceived as overly technical. The title generally does not have\nas stringent format requirements on it, so it may contain special\ncharacters and be more explanatory. Do keep it very short though, and\navoid situations where a title can be confused with the name of another\nentity, or where two entities share a title.\nNote that this is only for display purposes, and may be ignored by some\nparts of the code. Entity references still always make use of the `name`\nproperty, not the title.',
+              },
+              namespace: {
+                type: 'string',
+                description: 'The namespace that the entity belongs to.',
+              },
+              name: {
+                type: 'string',
+                description:
+                  'The name of the entity.\nMust be unique within the catalog at any given point in time, for any\ngiven namespace + kind pair. This value is part of the technical\nidentifier of the entity, and as such it will appear in URLs, database\ntables, entity references, and similar. It is subject to restrictions\nregarding what characters are allowed.\nIf you want to use a different, more human readable string with fewer\nrestrictions on it in user interfaces, see the `title` field below.',
+              },
+              etag: {
+                type: 'string',
+                description:
+                  'An opaque string that changes for each update operation to any part of\nthe entity, including metadata.\nThis field can not be set by the user at creation time, and the server\nwill reject an attempt to do so. The field will be populated in read\noperations. The field can (optionally) be specified when performing\nupdate or delete operations, and the server will then reject the\noperation if it does not match the current stored value.',
+              },
+              uid: {
+                type: 'string',
+                description:
+                  'A globally unique ID for the entity.\nThis field can not be set by the user at creation time, and the server\nwill reject an attempt to do so. The field will be populated in read\noperations. The field can (optionally) be specified when performing\nupdate or delete operations, but the server is free to reject requests\nthat do so in such a way that it breaks semantics.',
+              },
+            },
+            required: ['name'],
+          },
+        ],
+        description: 'Metadata fields common to all versions/kinds of entity.',
+      },
+      EntityRelation: {
+        type: 'object',
+        properties: {
+          targetRef: {
+            type: 'string',
+            description: 'The entity ref of the target of this relation.',
+          },
+          type: {
+            type: 'string',
+            description: 'The type of the relation.',
+          },
+        },
+        required: ['targetRef', 'type'],
+        description:
+          'A relation of a specific type to another entity in the catalog.',
+      },
+      Entity: {
+        type: 'object',
+        properties: {
+          relations: {
+            type: 'array',
+            items: {
+              $ref: '#/components/schemas/EntityRelation',
+            },
+            description:
+              'The relations that this entity has with other entities.',
+          },
+          spec: {
+            $ref: '#/components/schemas/JsonObject',
+          },
+          metadata: {
+            $ref: '#/components/schemas/EntityMeta',
+          },
+          kind: {
+            type: 'string',
+            description: 'The high level entity type being described.',
+          },
+          apiVersion: {
+            type: 'string',
+            description:
+              'The version of specification format for this particular entity that\nthis is written against.',
+          },
+        },
+        required: ['metadata', 'kind', 'apiVersion'],
+        description:
+          "The parts of the format that's common to all versions/kinds of entity.",
+      },
+      EntityAncestryResponse: {
+        type: 'object',
+        properties: {
+          items: {
+            type: 'array',
+            items: {
+              type: 'object',
+              properties: {
+                parentEntityRefs: {
+                  items: {
+                    type: 'string',
+                  },
+                  type: 'array',
+                },
+                entity: {
+                  $ref: '#/components/schemas/Entity',
+                },
+              },
+              required: ['parentEntityRefs', 'entity'],
+            },
+          },
+          rootEntityRef: {
+            type: 'string',
+          },
+        },
+        required: ['items', 'rootEntityRef'],
+      },
+      EntitiesBatchResponse: {
+        type: 'object',
+        properties: {
+          items: {
+            type: 'array',
+            items: {
+              allOf: [
+                {
+                  $ref: '#/components/schemas/Entity',
+                },
+              ],
+              nullable: true,
+            },
+            description:
+              'The list of entities, in the same order as the refs in the request. Entries\nthat are null signify that no entity existed with that ref.',
+          },
+        },
+        required: ['items'],
+      },
+      EntityFacets: {
+        type: 'object',
+        properties: {
+          value: {
+            type: 'string',
+          },
+          count: {
+            type: 'number',
+          },
+        },
+        description: 'Construct a type with a set of properties K of type T',
+      },
+      EntityFacetsResponse: {
+        type: 'object',
+        properties: {},
+        additionalProperties: {
+          $ref: '#/components/schemas/EntityFacets',
+        },
+        required: ['facets'],
+      },
+      Location: {
+        type: 'object',
+        properties: {
+          target: {
+            type: 'string',
+          },
+          type: {
+            type: 'string',
+          },
+          id: {
+            type: 'string',
+          },
+        },
+        required: ['target', 'type', 'id'],
+        description: 'Entity location for a specific entity.',
+      },
+      LocationSpec: {
+        type: 'object',
+        properties: {
+          presence: {
+            type: 'string',
+            enum: ['optional', 'required'],
+          },
+          target: {
+            type: 'string',
+          },
+          type: {
+            type: 'string',
+          },
+        },
+        required: ['target', 'type'],
+        description: 'Holds the entity location information.',
+      },
+      AnalyzeLocationExistingEntity: {
+        type: 'object',
+        properties: {
+          entity: {
+            $ref: '#/components/schemas/Entity',
+          },
+          isRegistered: {
+            type: 'boolean',
+          },
+          location: {
+            $ref: '#/components/schemas/LocationSpec',
+          },
+        },
+        required: ['entity', 'isRegistered', 'location'],
+        description:
+          "If the folder pointed to already contained catalog info yaml files, they are\nread and emitted like this so that the frontend can inform the user that it\nlocated them and can make sure to register them as well if they weren't\nalready",
+      },
+      RecursivePartial_Entity_: {
+        type: 'object',
+        properties: {
+          apiVersion: {
+            type: 'string',
+            description:
+              'The version of specification format for this particular entity that\nthis is written against.',
+          },
+          kind: {
+            type: 'string',
+            description: 'The high level entity type being described.',
+          },
+          metadata: {
+            $ref: '#/components/schemas/EntityMeta',
+          },
+          spec: {
+            $ref: '#/components/schemas/JsonObject',
+          },
+          relations: {
+            type: 'array',
+            items: {
+              $ref: '#/components/schemas/EntityRelation',
+            },
+            description:
+              'The relations that this entity has with other entities.',
+          },
+        },
+        description: 'Makes all keys of an entire hierarchy optional.',
+      },
+      AnalyzeLocationEntityField: {
+        type: 'object',
+        properties: {
+          description: {
+            type: 'string',
+            description:
+              'A text to show to the user to inform about the choices made. Like, it could say\n"Found a CODEOWNERS file that covers this target, so we suggest leaving this\nfield empty; which would currently make it owned by X" where X is taken from the\ncodeowners file.',
+          },
+          value: {
+            type: 'string',
+            nullable: true,
+          },
+          state: {
+            type: 'string',
+            enum: [
+              'analysisSuggestedValue',
+              'analysisSuggestedNoValue',
+              'needsUserInput',
+            ],
+            description:
+              'The outcome of the analysis for this particular field',
+          },
+          field: {
+            type: 'string',
+            description:
+              'e.g. "spec.owner"? The frontend needs to know how to "inject" the field into the\nentity again if the user wants to change it',
+          },
+        },
+        required: ['description', 'value', 'state', 'field'],
+      },
+      AnalyzeLocationGenerateEntity: {
+        type: 'object',
+        properties: {
+          fields: {
+            type: 'array',
+            items: {
+              $ref: '#/components/schemas/AnalyzeLocationEntityField',
+            },
+          },
+          entity: {
+            $ref: '#/components/schemas/RecursivePartial_Entity_',
+          },
+        },
+        required: ['fields', 'entity'],
+        description:
+          "This is some form of representation of what the analyzer could deduce.\nWe should probably have a chat about how this can best be conveyed to\nthe frontend. It'll probably contain a (possibly incomplete) entity, plus\nenough info for the frontend to know what form data to show to the user\nfor overriding/completing the info.",
+      },
+      AnalyzeLocationResponse: {
+        type: 'object',
+        properties: {
+          generateEntities: {
+            items: {
+              $ref: '#/components/schemas/AnalyzeLocationGenerateEntity',
+            },
+            type: 'array',
+          },
+          existingEntityFiles: {
+            items: {
+              $ref: '#/components/schemas/AnalyzeLocationExistingEntity',
+            },
+            type: 'array',
+          },
+        },
+        required: ['generateEntities', 'existingEntityFiles'],
+      },
+      LocationInput: {
+        type: 'object',
+        properties: {
+          type: {
+            type: 'string',
+          },
+          target: {
+            type: 'string',
+          },
+          presence: {
+            type: 'string',
+            enum: ['optional', 'required'],
+          },
+        },
+        required: ['type', 'target', 'presence'],
+      },
+      SerializedError: {
+        allOf: [
+          {
+            $ref: '#/components/schemas/JsonObject',
+          },
+          {
+            type: 'object',
+            properties: {
+              code: {
+                type: 'string',
+                description:
+                  'A custom code (not necessarily the same as an HTTP response code); may not be present',
+              },
+              stack: {
+                type: 'string',
+                description: 'A stringified stack trace; may not be present',
+              },
+              message: {
+                type: 'string',
+                description: 'The message of the exception that was thrown',
+              },
+              name: {
+                type: 'string',
+                description: 'The name of the exception that was thrown',
+              },
+            },
+            required: ['message', 'name'],
+          },
+        ],
+        description: 'The serialized form of an Error.',
+      },
+    },
+    securitySchemes: {
+      JWT: {
+        type: 'http',
+        scheme: 'bearer',
+        bearerFormat: 'JWT',
+      },
+    },
+  },
+  paths: {
+    '/refresh': {
+      post: {
+        operationId: 'RefreshEntity',
+        responses: {
+          '200': {
+            description: 'Refreshed',
+          },
+        },
+        security: [
+          {},
+          {
+            JWT: [],
+          },
+        ],
+        parameters: [],
+        requestBody: {
+          required: true,
+          content: {
+            'application/json': {
+              schema: {
+                $ref: '#/components/schemas/RefreshOptions',
+              },
+            },
+          },
+        },
+      },
+    },
+    '/entities': {
+      get: {
+        operationId: 'GetEntities',
+        responses: {
+          '200': {
+            description: '',
+            content: {
+              'application/json': {
+                schema: {
+                  type: 'array',
+                  items: {
+                    $ref: '#/components/schemas/Entity',
+                  },
+                },
+              },
+            },
+          },
+        },
+        security: [
+          {},
+          {
+            JWT: [],
+          },
+        ],
+        parameters: [
+          {
+            in: 'query',
+            name: 'filter',
+            required: false,
+            schema: {
+              type: 'string',
+            },
+          },
+          {
+            in: 'query',
+            name: 'fields',
+            required: false,
+            schema: {
+              type: 'string',
+            },
+          },
+          {
+            in: 'query',
+            name: 'offset',
+            required: false,
+            schema: {
+              type: 'string',
+            },
+          },
+          {
+            in: 'query',
+            name: 'limit',
+            required: false,
+            schema: {
+              type: 'string',
+            },
+          },
+          {
+            in: 'query',
+            name: 'after',
+            required: false,
+            schema: {
+              type: 'string',
+            },
+          },
+        ],
+      },
+    },
+    '/entities/by-uid/{uid}': {
+      get: {
+        operationId: 'GetEntityByUid',
+        responses: {
+          '200': {
+            description: 'Ok',
+            content: {
+              'application/json': {
+                schema: {
+                  $ref: '#/components/schemas/Entity',
+                },
+              },
+            },
+          },
+        },
+        security: [
+          {},
+          {
+            JWT: [],
+          },
+        ],
+        parameters: [
+          {
+            in: 'path',
+            name: 'uid',
+            required: true,
+            schema: {
+              type: 'string',
+            },
+          },
+        ],
+      },
+      delete: {
+        operationId: 'DeleteEntityByUid',
+        responses: {
+          '204': {
+            description: 'Deleted successfully.',
+          },
+        },
+        security: [
+          {},
+          {
+            JWT: [],
+          },
+        ],
+        parameters: [
+          {
+            in: 'path',
+            name: 'uid',
+            required: true,
+            schema: {
+              type: 'string',
+            },
+          },
+        ],
+      },
+    },
+    '/entities/by-name/{kind}/{namespace}/{name}': {
+      get: {
+        operationId: 'GetEntityByName',
+        responses: {
+          '200': {
+            description: 'Ok',
+            content: {
+              'application/json': {
+                schema: {
+                  $ref: '#/components/schemas/Entity',
+                },
+              },
+            },
+          },
+        },
+        security: [
+          {},
+          {
+            JWT: [],
+          },
+        ],
+        parameters: [
+          {
+            in: 'path',
+            name: 'kind',
+            required: true,
+            schema: {
+              type: 'string',
+            },
+          },
+          {
+            in: 'path',
+            name: 'namespace',
+            required: true,
+            schema: {
+              type: 'string',
+            },
+          },
+          {
+            in: 'path',
+            name: 'name',
+            required: true,
+            schema: {
+              type: 'string',
+            },
+          },
+        ],
+      },
+    },
+    '/entities/by-name/{kind}/{namespace}/{name}/ancestry': {
+      get: {
+        operationId: 'GetEntityAncestryByName',
+        responses: {
+          '200': {
+            description: 'Ok',
+            content: {
+              'application/json': {
+                schema: {
+                  $ref: '#/components/schemas/EntityAncestryResponse',
+                },
+              },
+            },
+          },
+        },
+        security: [
+          {},
+          {
+            JWT: [],
+          },
+        ],
+        parameters: [
+          {
+            in: 'path',
+            name: 'kind',
+            required: true,
+            schema: {
+              type: 'string',
+            },
+          },
+          {
+            in: 'path',
+            name: 'namespace',
+            required: true,
+            schema: {
+              type: 'string',
+            },
+          },
+          {
+            in: 'path',
+            name: 'name',
+            required: true,
+            schema: {
+              type: 'string',
+            },
+          },
+        ],
+      },
+    },
+    '/entities/by-refs': {
+      post: {
+        operationId: 'GetEntitiesByRefs',
+        responses: {
+          '200': {
+            description: 'Ok',
+            content: {
+              'application/json': {
+                schema: {
+                  $ref: '#/components/schemas/EntitiesBatchResponse',
+                },
+              },
+            },
+          },
+        },
+        security: [
+          {},
+          {
+            JWT: [],
+          },
+        ],
+        parameters: [
+          {
+            in: 'query',
+            name: 'fields',
+            required: false,
+            schema: {
+              type: 'string',
+            },
+          },
+        ],
+        requestBody: {
+          required: true,
+          content: {
+            'application/json': {
+              schema: {
+                type: 'array',
+                items: {
+                  type: 'string',
+                },
+              },
+            },
+          },
+        },
+      },
+    },
+    '/entity-facets': {
+      get: {
+        operationId: 'GetEntityFacets',
+        responses: {
+          '200': {
+            description: 'Ok',
+            content: {
+              'application/json': {
+                schema: {
+                  $ref: '#/components/schemas/EntityFacetsResponse',
+                },
+              },
+            },
+          },
+        },
+        security: [
+          {},
+          {
+            JWT: [],
+          },
+        ],
+        parameters: [
+          {
+            in: 'query',
+            name: 'facet',
+            required: true,
+            schema: {
+              type: 'string',
+            },
+          },
+          {
+            in: 'query',
+            name: 'filter',
+            required: false,
+            schema: {
+              type: 'string',
+            },
+          },
+        ],
+      },
+    },
+    '/locations': {
+      post: {
+        operationId: 'CreateLocation',
+        responses: {
+          '200': {
+            description: 'Ok',
+            content: {
+              'application/json': {
+                schema: {
+                  type: 'object',
+                  properties: {
+                    exists: {
+                      type: 'boolean',
+                    },
+                    entities: {
+                      items: {
+                        $ref: '#/components/schemas/Entity',
+                      },
+                      type: 'array',
+                    },
+                    location: {
+                      $ref: '#/components/schemas/Location',
+                    },
+                  },
+                  required: ['entities', 'location'],
+                },
+              },
+            },
+          },
+        },
+        security: [
+          {},
+          {
+            JWT: [],
+          },
+        ],
+        parameters: [
+          {
+            in: 'query',
+            name: 'dryRun',
+            required: false,
+            schema: {
+              type: 'boolean',
+            },
+          },
+        ],
+        requestBody: {
+          required: true,
+          content: {
+            'application/json': {
+              schema: {
+                type: 'object',
+                properties: {
+                  presence: {
+                    type: 'string',
+                    enum: ['required', 'optional'],
+                  },
+                  target: {
+                    type: 'string',
+                  },
+                  type: {
+                    type: 'string',
+                  },
+                },
+                required: ['presence', 'target', 'type'],
+              },
+            },
+          },
+        },
+      },
+      get: {
+        operationId: 'GetLocations',
+        responses: {
+          '200': {
+            description: 'Ok',
+            content: {
+              'application/json': {
+                schema: {
+                  type: 'array',
+                  items: {
+                    type: 'object',
+                    properties: {
+                      data: {
+                        $ref: '#/components/schemas/Location',
+                      },
+                    },
+                    required: ['data'],
+                  },
+                },
+              },
+            },
+          },
+        },
+        security: [
+          {},
+          {
+            JWT: [],
+          },
+        ],
+        parameters: [],
+      },
+    },
+    '/locations/{id}': {
+      get: {
+        operationId: 'GetLocation',
+        responses: {
+          '200': {
+            description: 'Ok',
+            content: {
+              'application/json': {
+                schema: {
+                  $ref: '#/components/schemas/Location',
+                },
+              },
+            },
+          },
+        },
+        security: [
+          {},
+          {
+            JWT: [],
+          },
+        ],
+        parameters: [
+          {
+            in: 'path',
+            name: 'id',
+            required: true,
+            schema: {
+              type: 'string',
+            },
+          },
+        ],
+      },
+      delete: {
+        operationId: 'DeleteLocation',
+        responses: {
+          '204': {
+            description: 'No content',
+          },
+        },
+        security: [
+          {},
+          {
+            JWT: [],
+          },
+        ],
+        parameters: [
+          {
+            in: 'path',
+            name: 'id',
+            required: true,
+            schema: {
+              type: 'string',
+            },
+          },
+        ],
+      },
+    },
+    '/analyze-location': {
+      post: {
+        operationId: 'AnalyzeLocation',
+        responses: {
+          '200': {
+            description: 'Ok',
+            content: {
+              'application/json': {
+                schema: {
+                  $ref: '#/components/schemas/AnalyzeLocationResponse',
+                },
+              },
+            },
+          },
+        },
+        security: [
+          {},
+          {
+            JWT: [],
+          },
+        ],
+        parameters: [],
+        requestBody: {
+          required: true,
+          content: {
+            'application/json': {
+              schema: {
+                type: 'object',
+                properties: {
+                  catalogFileName: {
+                    type: 'string',
+                  },
+                  location: {
+                    $ref: '#/components/schemas/LocationInput',
+                  },
+                },
+                required: ['catalogFileName', 'location'],
+              },
+            },
+          },
+        },
+      },
+    },
+    '/validate-entity': {
+      post: {
+        operationId: 'ValidateEntity',
+        responses: {
+          '200': {
+            description: 'Ok',
+            content: {
+              'application/json': {
+                schema: {
+                  anyOf: [
+                    {
+                      type: 'object',
+                      properties: {
+                        errors: {
+                          $ref: '#/components/schemas/SerializedError',
+                        },
+                      },
+                      required: ['errors'],
+                    },
+                    {
+                      type: 'object',
+                      properties: {
+                        errors: {
+                          type: 'array',
+                          items: {
+                            $ref: '#/components/schemas/SerializedError',
+                          },
+                        },
+                      },
+                      required: ['errors'],
+                    },
+                  ],
+                },
+              },
+            },
+          },
+        },
+        security: [
+          {},
+          {
+            JWT: [],
+          },
+        ],
+        parameters: [],
+        requestBody: {
+          required: true,
+          content: {
+            'application/json': {
+              schema: {
+                type: 'object',
+                properties: {
+                  location: {
+                    type: 'string',
+                  },
+                  entity: {
+                    $ref: '#/components/schemas/Entity',
+                  },
+                },
+                required: ['location', 'entity'],
+              },
+            },
+          },
+        },
+      },
+    },
+  },
+} as const;
diff --git a/plugins/openapi-router-common/package.json b/plugins/openapi-router-common/package.json
index 3a40ddecd0..b6dbd8cb63 100644
--- a/plugins/openapi-router-common/package.json
+++ b/plugins/openapi-router-common/package.json
@@ -34,6 +34,8 @@
     "json-schema-to-ts": "^2.6.2",
     "openapi-types": "^12.1.0",
     "openapi3-ts": "^3.1.2",
-    "ts-node": "^10.9.1"
+    "ts-node": "^10.9.1",
+    "winston": "^3.8.2",
+    "yn": "^5.0.0"
   }
 }
diff --git a/plugins/openapi-router-common/src/router.ts b/plugins/openapi-router-common/src/router.ts
index 99a45b8e0c..8703c691c5 100644
--- a/plugins/openapi-router-common/src/router.ts
+++ b/plugins/openapi-router-common/src/router.ts
@@ -14,11 +14,10 @@
  * limitations under the License.
  */
 import { OpenAPIV3, OpenAPIV3_1 } from 'openapi-types';
-import { IRouter, Router } from 'express';
+import { Router } from 'express';
 import core, { ParamsDictionary } from 'express-serve-static-core';
 import { FromSchema, JSONSchema7 } from 'json-schema-to-ts';
 import {
-  DocPath,
   DocPathMethod,
   DocPathTemplate,
   MethodAwareDocPath,
@@ -29,7 +28,9 @@ import {
 } from './types';
 import { ResponseSchemas } from './types/response';
 
-type DeepWriteable<T> = { -readonly [P in keyof T]: DeepWriteable<T[P]> };
+export type DeepWriteable<T> = {
+  -readonly [P in keyof T]: DeepWriteable<T[P]>;
+};
 
 const doc = {
   openapi: '3.1.0',
@@ -253,7 +254,7 @@ type ConvertAll<T, R extends ReadonlyArray<unknown> = []> = T extends [
   ? ConvertAll<Rest, [...R, FromSchema<First>]>
   : R;
 
-type ResponseToJsonSchema<
+type ResponseBodyToJsonSchema<
   Doc extends RequiredDoc,
   Path extends PathTemplate<Extract<keyof Doc['paths'], string>>,
   Method extends DocPathMethod<Doc, Path>,
@@ -261,6 +262,14 @@ type ResponseToJsonSchema<
   TuplifyUnion<ValueOf<ResponseSchemas<Doc, Path, Method>>>
 >[number];
 
+type RequestBodyToJsonSchema<
+  Doc extends RequiredDoc,
+  Path extends PathTemplate<Extract<keyof Doc['paths'], string>>,
+  Method extends DocPathMethod<Doc, Path>,
+> = ConvertAll<
+  TuplifyUnion<ValueOf<RequestBodySchema<Doc, Path, Method>>>
+>[number];
+
 type DocRequestHandler<
   Doc extends RequiredDoc,
   Path extends DocPathTemplate<Doc>,
@@ -268,13 +277,13 @@ type DocRequestHandler<
 > = core.RequestHandler<
   core.ParamsDictionary,
   // From https://stackoverflow.com/questions/71393738/typescript-intersection-not-union-type-from-json-schema.
-  ResponseToJsonSchema<Doc, Path, Method>,
-  RequestBodySchema<Doc, Path, Method>,
+  ResponseBodyToJsonSchema<Doc, Path, Method>,
+  RequestBodyToJsonSchema<Doc, Path, Method>,
   ParsedQs,
   Record<string, string>
 >;
 
-export default class ApiRouter<Doc extends RequiredDoc> {
+export class ApiRouter<Doc extends RequiredDoc> {
   private _router = Router();
 
   constructor(private spec: OpenAPIV3_1.Document | OpenAPIV3.Document) {}
@@ -372,7 +381,7 @@ export async function createRouter(options: RouterOptions) {
   router.get('/pets/:uid', (req, res) => {
     res.json({
       id: 1,
-      name: req.params['uid'],
+      name: req.params.uid,
     });
   });
 
diff --git a/plugins/openapi-router-common/src/types/common.ts b/plugins/openapi-router-common/src/types/common.ts
index 2f0d6735a4..f514c88d13 100644
--- a/plugins/openapi-router-common/src/types/common.ts
+++ b/plugins/openapi-router-common/src/types/common.ts
@@ -1,3 +1,19 @@
+/*
+ * Copyright 2023 The Backstage Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
 /**
  * Pulled from https://github.com/varanauskas/oatx.
  */
diff --git a/plugins/openapi-router-common/src/types/index.ts b/plugins/openapi-router-common/src/types/index.ts
index 758a48738d..8bd9fd0846 100644
--- a/plugins/openapi-router-common/src/types/index.ts
+++ b/plugins/openapi-router-common/src/types/index.ts
@@ -1,2 +1,17 @@
+/*
+ * Copyright 2023 The Backstage Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
 export * from './common';
 export * from './requests';
diff --git a/plugins/openapi-router-common/src/types/requests.ts b/plugins/openapi-router-common/src/types/requests.ts
index 49f30d0e94..832cf34956 100644
--- a/plugins/openapi-router-common/src/types/requests.ts
+++ b/plugins/openapi-router-common/src/types/requests.ts
@@ -1,6 +1,23 @@
+/*
+ * Copyright 2023 The Backstage Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
 /**
  * Pulled from https://github.com/varanauskas/oatx.
  */
+
 import type { ReferenceObject, RequestBodyObject } from 'openapi3-ts';
 import type {
   ComponentRef,
diff --git a/plugins/openapi-router-common/src/types/response.ts b/plugins/openapi-router-common/src/types/response.ts
index f4b2f0d92d..93ec8a61fa 100644
--- a/plugins/openapi-router-common/src/types/response.ts
+++ b/plugins/openapi-router-common/src/types/response.ts
@@ -1,6 +1,23 @@
+/*
+ * Copyright 2023 The Backstage Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
 /**
  * Pulled from https://github.com/varanauskas/oatx.
  */
+
 import type { ReferenceObject, ResponseObject } from 'openapi3-ts';
 import type {
   ComponentRef,
diff --git a/yarn.lock b/yarn.lock
index 0396822f80..b32c3fbf2f 100644
--- a/yarn.lock
+++ b/yarn.lock
@@ -5353,6 +5353,7 @@ __metadata:
     "@backstage/integration": "workspace:^"
     "@backstage/plugin-catalog-common": "workspace:^"
     "@backstage/plugin-catalog-node": "workspace:^"
+    "@backstage/plugin-openapi-router": "workspace:^"
     "@backstage/plugin-permission-common": "workspace:^"
     "@backstage/plugin-permission-node": "workspace:^"
     "@backstage/plugin-scaffolder-common": "workspace:^"
@@ -7446,7 +7447,7 @@ __metadata:
   languageName: unknown
   linkType: soft
 
-"@backstage/plugin-openapi-router@workspace:plugins/openapi-router-common":
+"@backstage/plugin-openapi-router@workspace:^, @backstage/plugin-openapi-router@workspace:plugins/openapi-router-common":
   version: 0.0.0-use.local
   resolution: "@backstage/plugin-openapi-router@workspace:plugins/openapi-router-common"
   dependencies:
@@ -7456,6 +7457,8 @@ __metadata:
     openapi-types: ^12.1.0
     openapi3-ts: ^3.1.2
     ts-node: ^10.9.1
+    winston: ^3.8.2
+    yn: ^5.0.0
   languageName: unknown
   linkType: soft
 
@@ -40279,7 +40282,7 @@ __metadata:
   languageName: node
   linkType: hard
 
-"winston@npm:^3.2.1":
+"winston@npm:^3.2.1, winston@npm:^3.8.2":
   version: 3.8.2
   resolution: "winston@npm:3.8.2"
   dependencies:

From 9076fab7036d4af7c12034e5c7f6f3cda5496b82 Mon Sep 17 00:00:00 2001
From: Aramis Sennyey <sennyeya@amazon.com>
Date: Thu, 16 Feb 2023 17:31:38 -0500
Subject: [PATCH 06/61] Small type fix.

Signed-off-by: Aramis Sennyey <sennyeya@amazon.com>
---
 plugins/catalog-backend/openapi.yaml          | 118 +++++++++++++++---
 .../src/service/createRouter.ts               |   8 +-
 .../src/service/schema/openapi.ts             | 102 +++++++++++++--
 plugins/openapi-router-common/src/router.ts   |  20 ++-
 4 files changed, 215 insertions(+), 33 deletions(-)

diff --git a/plugins/catalog-backend/openapi.yaml b/plugins/catalog-backend/openapi.yaml
index ea09f5da10..037b4633b0 100644
--- a/plugins/catalog-backend/openapi.yaml
+++ b/plugins/catalog-backend/openapi.yaml
@@ -207,19 +207,24 @@ components:
             that are null signify that no entity existed with that ref.
       required:
         - items
-    EntityFacets:
+    EntityFacet:
       type: object
       properties:
         value:
           type: string
         count:
           type: number
-      description: Construct a type with a set of properties K of type T
+    EntityFacets:
+      type: array
+      items:
+        $ref: '#/components/schemas/EntityFacet'
     EntityFacetsResponse:
       type: object
-      properties: {}
-      additionalProperties:
-        $ref: '#/components/schemas/EntityFacets'
+      properties:
+        facets:
+          type: object
+          additionalProperties:
+            $ref: '#/components/schemas/EntityFacets'
       required:
         - facets
     Location:
@@ -270,6 +275,91 @@ components:
         read and emitted like this so that the frontend can inform the user that it
         located them and can make sure to register them as well if they weren't
         already
+    RecursivePartialEntityRelation:
+      type: object
+      properties:
+        targetRef:
+          type: string
+          description: The entity ref of the target of this relation.
+        type:
+          type: string
+          description: The type of the relation.
+      description: A relation of a specific type to another entity in the catalog.
+    RecursivePartialEntityMeta:
+      allOf:
+        - $ref: '#/components/schemas/JsonObject'
+        - type: object
+          properties:
+            properties:
+            links:
+              type: array
+              items:
+                $ref: '#/components/schemas/EntityLink'
+              description: A list of external hyperlinks related to the entity.
+            tags:
+              type: array
+              items:
+                type: string
+              description: |-
+                A list of single-valued strings, to for example classify catalog entities in
+                various ways.
+            annotations:
+              $ref: '#/components/schemas/MapStringString'
+            labels:
+              $ref: '#/components/schemas/MapStringString'
+            description:
+              type: string
+              description: |-
+                A short (typically relatively few words, on one line) description of the
+                entity.
+            title:
+              type: string
+              description: |-
+                A display name of the entity, to be presented in user interfaces instead
+                of the `name` property above, when available.
+                This field is sometimes useful when the `name` is cumbersome or ends up
+                being perceived as overly technical. The title generally does not have
+                as stringent format requirements on it, so it may contain special
+                characters and be more explanatory. Do keep it very short though, and
+                avoid situations where a title can be confused with the name of another
+                entity, or where two entities share a title.
+                Note that this is only for display purposes, and may be ignored by some
+                parts of the code. Entity references still always make use of the `name`
+                property, not the title.
+            namespace:
+              type: string
+              description: The namespace that the entity belongs to.
+            name:
+              type: string
+              description: |-
+                The name of the entity.
+                Must be unique within the catalog at any given point in time, for any
+                given namespace + kind pair. This value is part of the technical
+                identifier of the entity, and as such it will appear in URLs, database
+                tables, entity references, and similar. It is subject to restrictions
+                regarding what characters are allowed.
+                If you want to use a different, more human readable string with fewer
+                restrictions on it in user interfaces, see the `title` field below.
+            etag:
+              type: string
+              description: |-
+                An opaque string that changes for each update operation to any part of
+                the entity, including metadata.
+                This field can not be set by the user at creation time, and the server
+                will reject an attempt to do so. The field will be populated in read
+                operations. The field can (optionally) be specified when performing
+                update or delete operations, and the server will then reject the
+                operation if it does not match the current stored value.
+            uid:
+              type: string
+              description: |-
+                A globally unique ID for the entity.
+                This field can not be set by the user at creation time, and the server
+                will reject an attempt to do so. The field will be populated in read
+                operations. The field can (optionally) be specified when performing
+                update or delete operations, but the server is free to reject requests
+                that do so in such a way that it breaks semantics.
+          description: Metadata fields common to all versions/kinds of entity.
     RecursivePartial_Entity_:
       type: object
       properties:
@@ -282,13 +372,13 @@ components:
           type: string
           description: The high level entity type being described.
         metadata:
-          $ref: '#/components/schemas/EntityMeta'
+          $ref: '#/components/schemas/RecursivePartialEntityMeta'
         spec:
           $ref: '#/components/schemas/JsonObject'
         relations:
           type: array
           items:
-            $ref: '#/components/schemas/EntityRelation'
+            $ref: '#/components/schemas/RecursivePartialEntityRelation'
           description: The relations that this entity has with other entities.
       description: Makes all keys of an entire hierarchy optional.
     AnalyzeLocationEntityField:
@@ -298,7 +388,7 @@ components:
           type: string
           description: |-
             A text to show to the user to inform about the choices made. Like, it could say
-            "Found a CODEOWNERS file that covers this target, so we suggest leaving this
+            "Found a CODEOWNERS file that covers this target, so we suggest leaving this 
             field empty; which would currently make it owned by X" where X is taken from the
             codeowners file.
         value:
@@ -395,7 +485,6 @@ components:
       type: http
       scheme: bearer
       bearerFormat: JWT
-
 paths:
   /refresh:
     post:
@@ -404,7 +493,6 @@ paths:
         '200':
           description: Refreshed
       security:
-        # From https://stackoverflow.com/questions/47659324/how-to-specify-an-endpoints-authorization-is-optional-in-openapi-v3
         - {}
         - JWT: []
       parameters: []
@@ -414,7 +502,6 @@ paths:
           application/json:
             schema:
               $ref: '#/components/schemas/RefreshOptions'
-
   /entities:
     get:
       operationId: GetEntities
@@ -456,7 +543,6 @@ paths:
           required: false
           schema:
             type: string
-
   /entities/by-uid/{uid}:
     get:
       operationId: GetEntityByUid
@@ -490,7 +576,6 @@ paths:
           required: true
           schema:
             type: string
-
   /entities/by-name/{kind}/{namespace}/{name}:
     get:
       operationId: GetEntityByName
@@ -520,7 +605,6 @@ paths:
           required: true
           schema:
             type: string
-
   /entities/by-name/{kind}/{namespace}/{name}/ancestry:
     get:
       operationId: GetEntityAncestryByName
@@ -550,7 +634,6 @@ paths:
           required: true
           schema:
             type: string
-
   /entities/by-refs:
     post:
       operationId: GetEntitiesByRefs
@@ -578,7 +661,6 @@ paths:
               type: array
               items:
                 type: string
-
   /entity-facets:
     get:
       operationId: GetEntityFacets
@@ -603,7 +685,6 @@ paths:
           required: false
           schema:
             type: string
-
   /locations:
     post:
       operationId: CreateLocation
@@ -675,7 +756,6 @@ paths:
         - {}
         - JWT: []
       parameters: []
-
   /locations/{id}:
     get:
       operationId: GetLocation
@@ -709,7 +789,6 @@ paths:
           required: true
           schema:
             type: string
-
   /analyze-location:
     post:
       operationId: AnalyzeLocation
@@ -738,7 +817,6 @@ paths:
               required:
                 - catalogFileName
                 - location
-
   /validate-entity:
     post:
       operationId: ValidateEntity
diff --git a/plugins/catalog-backend/src/service/createRouter.ts b/plugins/catalog-backend/src/service/createRouter.ts
index 19535bfec7..8b912ae6f1 100644
--- a/plugins/catalog-backend/src/service/createRouter.ts
+++ b/plugins/catalog-backend/src/service/createRouter.ts
@@ -189,7 +189,9 @@ export async function createRouter(
           fields: parseEntityTransformParams(req.query, request.fields),
           authorizationToken: token,
         });
-        res.status(200).json(response);
+        // These responses are interacting weirdly with the underlying interface passed to them,
+        //  we just need to re-load the TS server's short term memory.
+        res.status(200).json({ ...response });
       })
       .get('/entity-facets', async (req, res) => {
         const response = await entitiesCatalog.facets({
@@ -197,7 +199,9 @@ export async function createRouter(
           facets: parseEntityFacetParams(req.query),
           authorizationToken: getBearerToken(req.header('authorization')),
         });
-        res.status(200).json(response);
+        // These responses are interacting weirdly with the underlying interface passed to them,
+        //  we just need to re-load the TS server's short term memory.
+        res.status(200).json({ ...response });
       });
   }
 
diff --git a/plugins/catalog-backend/src/service/schema/openapi.ts b/plugins/catalog-backend/src/service/schema/openapi.ts
index a8f78a36ec..81e585ee01 100644
--- a/plugins/catalog-backend/src/service/schema/openapi.ts
+++ b/plugins/catalog-backend/src/service/schema/openapi.ts
@@ -250,7 +250,7 @@ export default {
         },
         required: ['items'],
       },
-      EntityFacets: {
+      EntityFacet: {
         type: 'object',
         properties: {
           value: {
@@ -260,13 +260,22 @@ export default {
             type: 'number',
           },
         },
-        description: 'Construct a type with a set of properties K of type T',
+      },
+      EntityFacets: {
+        type: 'array',
+        items: {
+          $ref: '#/components/schemas/EntityFacet',
+        },
       },
       EntityFacetsResponse: {
         type: 'object',
-        properties: {},
-        additionalProperties: {
-          $ref: '#/components/schemas/EntityFacets',
+        properties: {
+          facets: {
+            type: 'object',
+            additionalProperties: {
+              $ref: '#/components/schemas/EntityFacets',
+            },
+          },
         },
         required: ['facets'],
       },
@@ -320,6 +329,85 @@ export default {
         description:
           "If the folder pointed to already contained catalog info yaml files, they are\nread and emitted like this so that the frontend can inform the user that it\nlocated them and can make sure to register them as well if they weren't\nalready",
       },
+      RecursivePartialEntityRelation: {
+        type: 'object',
+        properties: {
+          targetRef: {
+            type: 'string',
+            description: 'The entity ref of the target of this relation.',
+          },
+          type: {
+            type: 'string',
+            description: 'The type of the relation.',
+          },
+        },
+        description:
+          'A relation of a specific type to another entity in the catalog.',
+      },
+      RecursivePartialEntityMeta: {
+        allOf: [
+          {
+            $ref: '#/components/schemas/JsonObject',
+          },
+          {
+            type: 'object',
+            properties: {
+              links: {
+                type: 'array',
+                items: {
+                  $ref: '#/components/schemas/EntityLink',
+                },
+                description:
+                  'A list of external hyperlinks related to the entity.',
+              },
+              tags: {
+                type: 'array',
+                items: {
+                  type: 'string',
+                },
+                description:
+                  'A list of single-valued strings, to for example classify catalog entities in\nvarious ways.',
+              },
+              annotations: {
+                $ref: '#/components/schemas/MapStringString',
+              },
+              labels: {
+                $ref: '#/components/schemas/MapStringString',
+              },
+              description: {
+                type: 'string',
+                description:
+                  'A short (typically relatively few words, on one line) description of the\nentity.',
+              },
+              title: {
+                type: 'string',
+                description:
+                  'A display name of the entity, to be presented in user interfaces instead\nof the `name` property above, when available.\nThis field is sometimes useful when the `name` is cumbersome or ends up\nbeing perceived as overly technical. The title generally does not have\nas stringent format requirements on it, so it may contain special\ncharacters and be more explanatory. Do keep it very short though, and\navoid situations where a title can be confused with the name of another\nentity, or where two entities share a title.\nNote that this is only for display purposes, and may be ignored by some\nparts of the code. Entity references still always make use of the `name`\nproperty, not the title.',
+              },
+              namespace: {
+                type: 'string',
+                description: 'The namespace that the entity belongs to.',
+              },
+              name: {
+                type: 'string',
+                description:
+                  'The name of the entity.\nMust be unique within the catalog at any given point in time, for any\ngiven namespace + kind pair. This value is part of the technical\nidentifier of the entity, and as such it will appear in URLs, database\ntables, entity references, and similar. It is subject to restrictions\nregarding what characters are allowed.\nIf you want to use a different, more human readable string with fewer\nrestrictions on it in user interfaces, see the `title` field below.',
+              },
+              etag: {
+                type: 'string',
+                description:
+                  'An opaque string that changes for each update operation to any part of\nthe entity, including metadata.\nThis field can not be set by the user at creation time, and the server\nwill reject an attempt to do so. The field will be populated in read\noperations. The field can (optionally) be specified when performing\nupdate or delete operations, and the server will then reject the\noperation if it does not match the current stored value.',
+              },
+              uid: {
+                type: 'string',
+                description:
+                  'A globally unique ID for the entity.\nThis field can not be set by the user at creation time, and the server\nwill reject an attempt to do so. The field will be populated in read\noperations. The field can (optionally) be specified when performing\nupdate or delete operations, but the server is free to reject requests\nthat do so in such a way that it breaks semantics.',
+              },
+            },
+          },
+        ],
+        description: 'Metadata fields common to all versions/kinds of entity.',
+      },
       RecursivePartial_Entity_: {
         type: 'object',
         properties: {
@@ -333,7 +421,7 @@ export default {
             description: 'The high level entity type being described.',
           },
           metadata: {
-            $ref: '#/components/schemas/EntityMeta',
+            $ref: '#/components/schemas/RecursivePartialEntityMeta',
           },
           spec: {
             $ref: '#/components/schemas/JsonObject',
@@ -341,7 +429,7 @@ export default {
           relations: {
             type: 'array',
             items: {
-              $ref: '#/components/schemas/EntityRelation',
+              $ref: '#/components/schemas/RecursivePartialEntityRelation',
             },
             description:
               'The relations that this entity has with other entities.',
diff --git a/plugins/openapi-router-common/src/router.ts b/plugins/openapi-router-common/src/router.ts
index 8703c691c5..3e0a08ffd6 100644
--- a/plugins/openapi-router-common/src/router.ts
+++ b/plugins/openapi-router-common/src/router.ts
@@ -14,7 +14,7 @@
  * limitations under the License.
  */
 import { OpenAPIV3, OpenAPIV3_1 } from 'openapi-types';
-import { Router } from 'express';
+import { ErrorRequestHandler, RequestHandler, Router } from 'express';
 import core, { ParamsDictionary } from 'express-serve-static-core';
 import { FromSchema, JSONSchema7 } from 'json-schema-to-ts';
 import {
@@ -283,6 +283,17 @@ type DocRequestHandler<
   Record<string, string>
 >;
 
+export type RequestHandlerParams<
+  P = ParamsDictionary,
+  ResBody = any,
+  ReqBody = any,
+  ReqQuery = ParsedQs,
+  LocalsObj extends Record<string, any> = Record<string, any>,
+> =
+  | RequestHandler<P, ResBody, ReqBody, ReqQuery, LocalsObj>
+  | ErrorRequestHandler<P, ResBody, ReqBody, ReqQuery, LocalsObj>
+  | Array<RequestHandler<P> | ErrorRequestHandler<P>>;
+
 export class ApiRouter<Doc extends RequiredDoc> {
   private _router = Router();
 
@@ -298,7 +309,7 @@ export class ApiRouter<Doc extends RequiredDoc> {
     path: Path,
     ...handlers: DocRequestHandler<Doc, Path, 'get'>[]
   ) {
-    console.log(path);
+    console.log(path, this.spec);
     this._router.get(path, ...handlers);
     return this;
   }
@@ -361,8 +372,8 @@ export class ApiRouter<Doc extends RequiredDoc> {
     return this;
   }
 
-  use(...handlers: core.RequestHandler[]) {
-    return this._router.use(handlers);
+  use(...handlers: RequestHandlerParams[]) {
+    return this._router.use(...handlers);
   }
 
   build() {
@@ -373,6 +384,7 @@ export class ApiRouter<Doc extends RequiredDoc> {
 interface RouterOptions {}
 
 export async function createRouter(options: RouterOptions) {
+  console.log(options);
   const router = ApiRouter.fromSpec<DeepWriteable<typeof doc>>(
     // As const forces the doc to readonly which conflicts with imported types.
     doc as DeepWriteable<typeof doc>,

From 6f4b8d9933264c47362dce3ad3e6cfbdd9fb58c3 Mon Sep 17 00:00:00 2001
From: Aramis Sennyey <sennyeya@amazon.com>
Date: Fri, 17 Feb 2023 17:13:51 -0500
Subject: [PATCH 07/61] dedupe yarn file.

Signed-off-by: Aramis Sennyey <sennyeya@amazon.com>
---
 .../src/service/createRouter.ts               |   8 +-
 plugins/openapi-router-common/package.json    |   2 +-
 plugins/openapi-router-common/src/router.ts   | 111 ++++++------------
 yarn.lock                                     |  47 ++++----
 4 files changed, 59 insertions(+), 109 deletions(-)

diff --git a/plugins/catalog-backend/src/service/createRouter.ts b/plugins/catalog-backend/src/service/createRouter.ts
index 8b912ae6f1..5da996546d 100644
--- a/plugins/catalog-backend/src/service/createRouter.ts
+++ b/plugins/catalog-backend/src/service/createRouter.ts
@@ -24,7 +24,7 @@ import {
 } from '@backstage/catalog-model';
 import { Config } from '@backstage/config';
 import { NotFoundError, serializeError } from '@backstage/errors';
-import express from 'express';
+import express, { Router } from 'express';
 import { Logger } from 'winston';
 import yn from 'yn';
 import { z } from 'zod';
@@ -86,9 +86,7 @@ export async function createRouter(
     logger,
     permissionIntegrationRouter,
   } = options;
-  const router = new ApiRouter<DeepWriteable<typeof spec>>(
-    spec as DeepWriteable<typeof spec>,
-  );
+  const router = Router() as ApiRouter<DeepWriteable<typeof spec>>;
   router.use(express.json());
 
   const readonlyEnabled =
@@ -312,7 +310,7 @@ export async function createRouter(
   }
 
   router.use(errorHandler());
-  return router.build();
+  return router;
 }
 
 function getBearerToken(
diff --git a/plugins/openapi-router-common/package.json b/plugins/openapi-router-common/package.json
index b6dbd8cb63..06a4c4e8ee 100644
--- a/plugins/openapi-router-common/package.json
+++ b/plugins/openapi-router-common/package.json
@@ -36,6 +36,6 @@
     "openapi3-ts": "^3.1.2",
     "ts-node": "^10.9.1",
     "winston": "^3.8.2",
-    "yn": "^5.0.0"
+    "yn": "^4.0.0"
   }
 }
diff --git a/plugins/openapi-router-common/src/router.ts b/plugins/openapi-router-common/src/router.ts
index 3e0a08ffd6..62e116727b 100644
--- a/plugins/openapi-router-common/src/router.ts
+++ b/plugins/openapi-router-common/src/router.ts
@@ -13,7 +13,6 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-import { OpenAPIV3, OpenAPIV3_1 } from 'openapi-types';
 import { ErrorRequestHandler, RequestHandler, Router } from 'express';
 import core, { ParamsDictionary } from 'express-serve-static-core';
 import { FromSchema, JSONSchema7 } from 'json-schema-to-ts';
@@ -269,6 +268,15 @@ type RequestBodyToJsonSchema<
 > = ConvertAll<
   TuplifyUnion<ValueOf<RequestBodySchema<Doc, Path, Method>>>
 >[number];
+export type RequestHandlerParams<
+  P,
+  ResBody,
+  ReqBody,
+  ReqQuery,
+  LocalsObj extends Record<string, any>,
+> =
+  | RequestHandler<P, ResBody, ReqBody, ReqQuery, LocalsObj>
+  | ErrorRequestHandler<P, ResBody, ReqBody, ReqQuery, LocalsObj>;
 
 type DocRequestHandler<
   Doc extends RequiredDoc,
@@ -283,112 +291,63 @@ type DocRequestHandler<
   Record<string, string>
 >;
 
-export type RequestHandlerParams<
-  P = ParamsDictionary,
-  ResBody = any,
-  ReqBody = any,
-  ReqQuery = ParsedQs,
-  LocalsObj extends Record<string, any> = Record<string, any>,
-> =
-  | RequestHandler<P, ResBody, ReqBody, ReqQuery, LocalsObj>
-  | ErrorRequestHandler<P, ResBody, ReqBody, ReqQuery, LocalsObj>
-  | Array<RequestHandler<P> | ErrorRequestHandler<P>>;
-
-export class ApiRouter<Doc extends RequiredDoc> {
-  private _router = Router();
-
-  constructor(private spec: OpenAPIV3_1.Document | OpenAPIV3.Document) {}
-
-  static fromSpec<Doc extends RequiredDoc>(
-    spec: OpenAPIV3_1.Document | OpenAPIV3.Document,
-  ) {
-    return new ApiRouter<Doc>(spec);
-  }
+export interface ApiRouterMatcher<
+  Doc extends RequiredDoc,
+  Path extends DocPathTemplate<Doc>,
+  Method extends DocPathMethod<Doc, Path>,
+  T,
+> {
+  (
+    path: MethodAwareDocPath<Doc, Path, Method>,
+    ...handlers: Array<DocRequestHandler<Doc, Path, Method>>
+  ): T;
+}
 
+export interface ApiRouter<Doc extends RequiredDoc> extends Router {
   get<Path extends MethodAwareDocPath<Doc, DocPathTemplate<Doc>, 'get'>>(
     path: Path,
     ...handlers: DocRequestHandler<Doc, Path, 'get'>[]
-  ) {
-    console.log(path, this.spec);
-    this._router.get(path, ...handlers);
-    return this;
-  }
+  ): this;
 
   post<Path extends MethodAwareDocPath<Doc, DocPathTemplate<Doc>, 'post'>>(
     path: Path,
     ...handlers: DocRequestHandler<Doc, Path, 'post'>[]
-  ) {
-    console.log(path);
-    this._router.post(path, ...handlers);
-    return this;
-  }
+  ): this;
 
   all<Path extends MethodAwareDocPath<Doc, DocPathTemplate<Doc>, 'all'>>(
     path: Path,
     ...handlers: DocRequestHandler<Doc, Path, 'all'>[]
-  ) {
-    console.log(path);
-    this._router.all(path, ...handlers);
-    return this;
-  }
+  ): this;
 
   put<Path extends MethodAwareDocPath<Doc, DocPathTemplate<Doc>, 'put'>>(
     path: Path,
     ...handlers: DocRequestHandler<Doc, Path, 'put'>[]
-  ) {
-    console.log(path);
-    this._router.put(path, ...handlers);
-    return this;
-  }
+  ): this;
   delete<Path extends MethodAwareDocPath<Doc, DocPathTemplate<Doc>, 'delete'>>(
     path: Path,
     ...handlers: DocRequestHandler<Doc, Path, 'delete'>[]
-  ) {
-    console.log(path);
-    this._router.delete(path, ...handlers);
-    return this;
-  }
+  ): this;
   patch<Path extends MethodAwareDocPath<Doc, DocPathTemplate<Doc>, 'patch'>>(
     path: Path,
     ...handlers: DocRequestHandler<Doc, Path, 'patch'>[]
-  ) {
-    console.log(path);
-    this._router.patch(path, ...handlers);
-    return this;
-  }
+  ): this;
   options<
     Path extends MethodAwareDocPath<Doc, DocPathTemplate<Doc>, 'options'>,
-  >(path: Path, ...handlers: DocRequestHandler<Doc, Path, 'options'>[]) {
-    console.log(path);
-    this._router.options(path, ...handlers);
-    return this;
-  }
+  >(
+    path: Path,
+    ...handlers: DocRequestHandler<Doc, Path, 'options'>[]
+  ): this;
   head<Path extends MethodAwareDocPath<Doc, DocPathTemplate<Doc>, 'head'>>(
     path: Path,
     ...handlers: DocRequestHandler<Doc, Path, 'head'>[]
-  ) {
-    console.log(path);
-    this._router.head(path, ...handlers);
-    return this;
-  }
-
-  use(...handlers: RequestHandlerParams[]) {
-    return this._router.use(...handlers);
-  }
-
-  build() {
-    return this._router;
-  }
+  ): this;
 }
 
 interface RouterOptions {}
 
 export async function createRouter(options: RouterOptions) {
   console.log(options);
-  const router = ApiRouter.fromSpec<DeepWriteable<typeof doc>>(
-    // As const forces the doc to readonly which conflicts with imported types.
-    doc as DeepWriteable<typeof doc>,
-  );
+  const router = Router() as ApiRouter<DeepWriteable<typeof doc>>;
 
   router.get('/pets/:uid', (req, res) => {
     res.json({
@@ -400,10 +359,10 @@ export async function createRouter(options: RouterOptions) {
   // router.get('/pet') will complain with a TS error
 
   router.post('/pets', (req, res) => {
-    res.json({
+    res.send({
       message: req.path,
       code: 1,
     });
   });
-  return router.build();
+  return router;
 }
diff --git a/yarn.lock b/yarn.lock
index b32c3fbf2f..9810ede5b8 100644
--- a/yarn.lock
+++ b/yarn.lock
@@ -7458,7 +7458,7 @@ __metadata:
     openapi3-ts: ^3.1.2
     ts-node: ^10.9.1
     winston: ^3.8.2
-    yn: ^5.0.0
+    yn: ^4.0.0
   languageName: unknown
   linkType: soft
 
@@ -24966,16 +24966,16 @@ __metadata:
   languageName: node
   linkType: hard
 
-"glob@npm:*, glob@npm:8.0.3":
-  version: 8.0.3
-  resolution: "glob@npm:8.0.3"
+"glob@npm:*, glob@npm:^8.0.0, glob@npm:^8.0.1, glob@npm:^8.0.3":
+  version: 8.1.0
+  resolution: "glob@npm:8.1.0"
   dependencies:
     fs.realpath: ^1.0.0
     inflight: ^1.0.4
     inherits: 2
     minimatch: ^5.0.1
     once: ^1.3.0
-  checksum: 50bcdea19d8e79d8de5f460b1939ffc2b3299eac28deb502093fdca22a78efebc03e66bf54f0abc3d3d07d8134d19a32850288b7440d77e072aa55f9d33b18c5
+  checksum: 92fbea3221a7d12075f26f0227abac435de868dd0736a17170663783296d0dd8d3d532a5672b4488a439bf5d7fb85cdd07c11185d6cd39184f0385cbdfb86a47
   languageName: node
   linkType: hard
 
@@ -24993,6 +24993,19 @@ __metadata:
   languageName: node
   linkType: hard
 
+"glob@npm:8.0.3":
+  version: 8.0.3
+  resolution: "glob@npm:8.0.3"
+  dependencies:
+    fs.realpath: ^1.0.0
+    inflight: ^1.0.4
+    inherits: 2
+    minimatch: ^5.0.1
+    once: ^1.3.0
+  checksum: 50bcdea19d8e79d8de5f460b1939ffc2b3299eac28deb502093fdca22a78efebc03e66bf54f0abc3d3d07d8134d19a32850288b7440d77e072aa55f9d33b18c5
+  languageName: node
+  linkType: hard
+
 "glob@npm:^7.0.0, glob@npm:^7.1.1, glob@npm:^7.1.3, glob@npm:^7.1.4, glob@npm:^7.1.6, glob@npm:^7.1.7, glob@npm:^7.2.0":
   version: 7.2.3
   resolution: "glob@npm:7.2.3"
@@ -25007,19 +25020,6 @@ __metadata:
   languageName: node
   linkType: hard
 
-"glob@npm:^8.0.0, glob@npm:^8.0.1, glob@npm:^8.0.3":
-  version: 8.1.0
-  resolution: "glob@npm:8.1.0"
-  dependencies:
-    fs.realpath: ^1.0.0
-    inflight: ^1.0.4
-    inherits: 2
-    minimatch: ^5.0.1
-    once: ^1.3.0
-  checksum: 92fbea3221a7d12075f26f0227abac435de868dd0736a17170663783296d0dd8d3d532a5672b4488a439bf5d7fb85cdd07c11185d6cd39184f0385cbdfb86a47
-  languageName: node
-  linkType: hard
-
 "global-agent@npm:^3.0.0":
   version: 3.0.0
   resolution: "global-agent@npm:3.0.0"
@@ -38649,20 +38649,13 @@ __metadata:
   languageName: node
   linkType: hard
 
-"ts-log@npm:^2.1.4":
+"ts-log@npm:^2.1.4, ts-log@npm:^2.2.3":
   version: 2.2.5
   resolution: "ts-log@npm:2.2.5"
   checksum: 28f78ab15b8555d56c089dbc243327d8ce4331219956242a29fc4cb3bad6bb0cb8234dd17a292381a1b1dba99a7e4849a2181b2e1a303e8247e9f4ca4e284f2d
   languageName: node
   linkType: hard
 
-"ts-log@npm:^2.2.3":
-  version: 2.2.3
-  resolution: "ts-log@npm:2.2.3"
-  checksum: 8aa34a2724d7915ddc6de8d0c27eb48f67206b52c42656f1ea2a7ffb080fa664db5fb22b42bd3c72b5b95cc6eb4612196b7d1e28f4bc146191ebc2a9683af548
-  languageName: node
-  linkType: hard
-
 "ts-morph@npm:^17.0.0":
   version: 17.0.1
   resolution: "ts-morph@npm:17.0.1"
@@ -40618,7 +40611,7 @@ __metadata:
   languageName: node
   linkType: hard
 
-"yaml@npm:^2.0.0, yaml@npm:^2.1.1, yaml@npm:^2.2.1":
+"yaml@npm:^2.0.0, yaml@npm:^2.1.1, yaml@npm:^2.1.3, yaml@npm:^2.2.1":
   version: 2.2.1
   resolution: "yaml@npm:2.2.1"
   checksum: 84f68cbe462d5da4e7ded4a8bded949ffa912bc264472e5a684c3d45b22d8f73a3019963a32164023bdf3d83cfb6f5b58ff7b2b10ef5b717c630f40bd6369a23

From 1bd272b2f1b75ed16cacbdc08f2a2f60fe44f9a3 Mon Sep 17 00:00:00 2001
From: Aramis Sennyey <sennyeya@amazon.com>
Date: Wed, 22 Feb 2023 10:42:45 -0500
Subject: [PATCH 08/61] Update yarn.lock file.

Signed-off-by: Aramis Sennyey <sennyeya@amazon.com>
---
 yarn.lock | 551 ++++++++++++++++++++++++++++++++++++++++++------------
 1 file changed, 428 insertions(+), 123 deletions(-)

diff --git a/yarn.lock b/yarn.lock
index 9810ede5b8..8152fac354 100644
--- a/yarn.lock
+++ b/yarn.lock
@@ -1,6 +1,3 @@
-# This file is generated by running "yarn install" inside your project.
-# Manual changes might be lost - proceed with caution!
-
 __metadata:
   version: 6
   cacheKey: 8
@@ -499,6 +496,15 @@ __metadata:
   languageName: node
   linkType: hard
 
+"@aws-sdk/chunked-blob-reader@npm:3.188.0":
+  version: 3.188.0
+  resolution: "@aws-sdk/chunked-blob-reader@npm:3.188.0"
+  dependencies:
+    tslib: ^2.3.1
+  checksum: d6becebc6d77a63dd84601806c5f04bc9d0e418368fb2d593d786738119091e4d2e40721751be66260063fe7bb1c7ee2a5e075fa731eb8307722b90f6ce809dc
+  languageName: node
+  linkType: hard
+
 "@aws-sdk/chunked-blob-reader@npm:3.295.0":
   version: 3.295.0
   resolution: "@aws-sdk/chunked-blob-reader@npm:3.295.0"
@@ -508,6 +514,92 @@ __metadata:
   languageName: node
   linkType: hard
 
+"@aws-sdk/client-cognito-identity@npm:3.272.0":
+  version: 3.272.0
+  resolution: "@aws-sdk/client-cognito-identity@npm:3.272.0"
+  dependencies:
+    "@aws-crypto/sha256-browser": 3.0.0
+    "@aws-crypto/sha256-js": 3.0.0
+    "@aws-sdk/client-sts": 3.272.0
+    "@aws-sdk/config-resolver": 3.272.0
+    "@aws-sdk/credential-provider-node": 3.272.0
+    "@aws-sdk/fetch-http-handler": 3.272.0
+    "@aws-sdk/hash-node": 3.272.0
+    "@aws-sdk/invalid-dependency": 3.272.0
+    "@aws-sdk/middleware-content-length": 3.282.0
+    "@aws-sdk/middleware-endpoint": 3.282.0
+    "@aws-sdk/middleware-host-header": 3.282.0
+    "@aws-sdk/middleware-logger": 3.272.0
+    "@aws-sdk/middleware-recursion-detection": 3.282.0
+    "@aws-sdk/middleware-retry": 3.282.0
+    "@aws-sdk/middleware-serde": 3.272.0
+    "@aws-sdk/middleware-signing": 3.282.0
+    "@aws-sdk/middleware-stack": 3.272.0
+    "@aws-sdk/middleware-user-agent": 3.282.0
+    "@aws-sdk/node-config-provider": 3.272.0
+    "@aws-sdk/node-http-handler": 3.282.0
+    "@aws-sdk/protocol-http": 3.282.0
+    "@aws-sdk/smithy-client": 3.279.0
+    "@aws-sdk/types": 3.272.0
+    "@aws-sdk/url-parser": 3.272.0
+    "@aws-sdk/util-base64": 3.208.0
+    "@aws-sdk/util-body-length-browser": 3.188.0
+    "@aws-sdk/util-body-length-node": 3.208.0
+    "@aws-sdk/util-defaults-mode-browser": 3.279.0
+    "@aws-sdk/util-defaults-mode-node": 3.282.0
+    "@aws-sdk/util-endpoints": 3.272.0
+    "@aws-sdk/util-retry": 3.272.0
+    "@aws-sdk/util-user-agent-browser": 3.282.0
+    "@aws-sdk/util-user-agent-node": 3.282.0
+    "@aws-sdk/util-utf8": 3.254.0
+    tslib: ^2.3.1
+  checksum: fd17c705b2de99fd1570239b62032525380b5e17799fc15f720196a488889fa10bbccd01952d5694ca8c20249d8a808de86de07d5a1b0d21486964a70d9b6d4d
+  languageName: node
+  linkType: hard
+
+"@aws-sdk/client-cognito-identity@npm:3.282.0":
+  version: 3.282.0
+  resolution: "@aws-sdk/client-cognito-identity@npm:3.282.0"
+  dependencies:
+    "@aws-crypto/sha256-browser": 3.0.0
+    "@aws-crypto/sha256-js": 3.0.0
+    "@aws-sdk/client-sts": 3.299.0
+    "@aws-sdk/config-resolver": 3.299.0
+    "@aws-sdk/credential-provider-node": 3.299.0
+    "@aws-sdk/fetch-http-handler": 3.296.0
+    "@aws-sdk/hash-node": 3.296.0
+    "@aws-sdk/invalid-dependency": 3.296.0
+    "@aws-sdk/middleware-content-length": 3.296.0
+    "@aws-sdk/middleware-endpoint": 3.299.0
+    "@aws-sdk/middleware-host-header": 3.296.0
+    "@aws-sdk/middleware-logger": 3.296.0
+    "@aws-sdk/middleware-recursion-detection": 3.296.0
+    "@aws-sdk/middleware-retry": 3.296.0
+    "@aws-sdk/middleware-serde": 3.296.0
+    "@aws-sdk/middleware-signing": 3.299.0
+    "@aws-sdk/middleware-stack": 3.296.0
+    "@aws-sdk/middleware-user-agent": 3.299.0
+    "@aws-sdk/node-config-provider": 3.296.0
+    "@aws-sdk/node-http-handler": 3.296.0
+    "@aws-sdk/protocol-http": 3.296.0
+    "@aws-sdk/smithy-client": 3.296.0
+    "@aws-sdk/types": 3.296.0
+    "@aws-sdk/url-parser": 3.296.0
+    "@aws-sdk/util-base64": 3.295.0
+    "@aws-sdk/util-body-length-browser": 3.295.0
+    "@aws-sdk/util-body-length-node": 3.295.0
+    "@aws-sdk/util-defaults-mode-browser": 3.296.0
+    "@aws-sdk/util-defaults-mode-node": 3.299.0
+    "@aws-sdk/util-endpoints": 3.296.0
+    "@aws-sdk/util-retry": 3.296.0
+    "@aws-sdk/util-user-agent-browser": 3.299.0
+    "@aws-sdk/util-user-agent-node": 3.299.0
+    "@aws-sdk/util-utf8": 3.295.0
+    tslib: ^2.5.0
+  checksum: fdcf53a12c4d5a4b71e29cac553c1aa8137fa4e5df3c23134f168618f4bd10e2480786a3de50bc9fab66aead74bd359bdbc5bf64c4d3553d71eb2488377a3f1f
+  languageName: node
+  linkType: hard
+
 "@aws-sdk/client-cognito-identity@npm:3.299.0":
   version: 3.299.0
   resolution: "@aws-sdk/client-cognito-identity@npm:3.299.0"
@@ -552,110 +644,110 @@ __metadata:
   linkType: hard
 
 "@aws-sdk/client-s3@npm:^3.208.0":
-  version: 3.299.0
-  resolution: "@aws-sdk/client-s3@npm:3.299.0"
+  version: 3.272.0
+  resolution: "@aws-sdk/client-s3@npm:3.272.0"
   dependencies:
     "@aws-crypto/sha1-browser": 3.0.0
     "@aws-crypto/sha256-browser": 3.0.0
     "@aws-crypto/sha256-js": 3.0.0
-    "@aws-sdk/client-sts": 3.299.0
-    "@aws-sdk/config-resolver": 3.299.0
-    "@aws-sdk/credential-provider-node": 3.299.0
-    "@aws-sdk/eventstream-serde-browser": 3.296.0
-    "@aws-sdk/eventstream-serde-config-resolver": 3.296.0
-    "@aws-sdk/eventstream-serde-node": 3.299.0
-    "@aws-sdk/fetch-http-handler": 3.296.0
-    "@aws-sdk/hash-blob-browser": 3.299.0
-    "@aws-sdk/hash-node": 3.296.0
-    "@aws-sdk/hash-stream-node": 3.296.0
-    "@aws-sdk/invalid-dependency": 3.296.0
-    "@aws-sdk/md5-js": 3.296.0
-    "@aws-sdk/middleware-bucket-endpoint": 3.299.0
-    "@aws-sdk/middleware-content-length": 3.296.0
-    "@aws-sdk/middleware-endpoint": 3.299.0
-    "@aws-sdk/middleware-expect-continue": 3.296.0
-    "@aws-sdk/middleware-flexible-checksums": 3.296.0
-    "@aws-sdk/middleware-host-header": 3.296.0
-    "@aws-sdk/middleware-location-constraint": 3.296.0
-    "@aws-sdk/middleware-logger": 3.296.0
-    "@aws-sdk/middleware-recursion-detection": 3.296.0
-    "@aws-sdk/middleware-retry": 3.296.0
-    "@aws-sdk/middleware-sdk-s3": 3.296.0
-    "@aws-sdk/middleware-serde": 3.296.0
-    "@aws-sdk/middleware-signing": 3.299.0
-    "@aws-sdk/middleware-ssec": 3.296.0
-    "@aws-sdk/middleware-stack": 3.296.0
-    "@aws-sdk/middleware-user-agent": 3.299.0
-    "@aws-sdk/node-config-provider": 3.296.0
-    "@aws-sdk/node-http-handler": 3.296.0
-    "@aws-sdk/protocol-http": 3.296.0
-    "@aws-sdk/signature-v4-multi-region": 3.299.0
-    "@aws-sdk/smithy-client": 3.296.0
-    "@aws-sdk/types": 3.296.0
-    "@aws-sdk/url-parser": 3.296.0
-    "@aws-sdk/util-base64": 3.295.0
-    "@aws-sdk/util-body-length-browser": 3.295.0
-    "@aws-sdk/util-body-length-node": 3.295.0
-    "@aws-sdk/util-defaults-mode-browser": 3.296.0
-    "@aws-sdk/util-defaults-mode-node": 3.299.0
-    "@aws-sdk/util-endpoints": 3.296.0
-    "@aws-sdk/util-retry": 3.296.0
-    "@aws-sdk/util-stream-browser": 3.296.0
-    "@aws-sdk/util-stream-node": 3.296.0
-    "@aws-sdk/util-user-agent-browser": 3.299.0
-    "@aws-sdk/util-user-agent-node": 3.299.0
-    "@aws-sdk/util-utf8": 3.295.0
-    "@aws-sdk/util-waiter": 3.296.0
-    "@aws-sdk/xml-builder": 3.295.0
+    "@aws-sdk/client-sts": 3.272.0
+    "@aws-sdk/config-resolver": 3.272.0
+    "@aws-sdk/credential-provider-node": 3.272.0
+    "@aws-sdk/eventstream-serde-browser": 3.272.0
+    "@aws-sdk/eventstream-serde-config-resolver": 3.272.0
+    "@aws-sdk/eventstream-serde-node": 3.272.0
+    "@aws-sdk/fetch-http-handler": 3.282.0
+    "@aws-sdk/hash-blob-browser": 3.272.0
+    "@aws-sdk/hash-node": 3.272.0
+    "@aws-sdk/hash-stream-node": 3.272.0
+    "@aws-sdk/invalid-dependency": 3.272.0
+    "@aws-sdk/md5-js": 3.272.0
+    "@aws-sdk/middleware-bucket-endpoint": 3.282.0
+    "@aws-sdk/middleware-content-length": 3.282.0
+    "@aws-sdk/middleware-endpoint": 3.282.0
+    "@aws-sdk/middleware-expect-continue": 3.282.0
+    "@aws-sdk/middleware-flexible-checksums": 3.282.0
+    "@aws-sdk/middleware-host-header": 3.282.0
+    "@aws-sdk/middleware-location-constraint": 3.272.0
+    "@aws-sdk/middleware-logger": 3.272.0
+    "@aws-sdk/middleware-recursion-detection": 3.282.0
+    "@aws-sdk/middleware-retry": 3.282.0
+    "@aws-sdk/middleware-sdk-s3": 3.282.0
+    "@aws-sdk/middleware-serde": 3.272.0
+    "@aws-sdk/middleware-signing": 3.282.0
+    "@aws-sdk/middleware-ssec": 3.272.0
+    "@aws-sdk/middleware-stack": 3.272.0
+    "@aws-sdk/middleware-user-agent": 3.282.0
+    "@aws-sdk/node-config-provider": 3.272.0
+    "@aws-sdk/node-http-handler": 3.282.0
+    "@aws-sdk/protocol-http": 3.282.0
+    "@aws-sdk/signature-v4-multi-region": 3.282.0
+    "@aws-sdk/smithy-client": 3.279.0
+    "@aws-sdk/types": 3.272.0
+    "@aws-sdk/url-parser": 3.272.0
+    "@aws-sdk/util-base64": 3.208.0
+    "@aws-sdk/util-body-length-browser": 3.188.0
+    "@aws-sdk/util-body-length-node": 3.208.0
+    "@aws-sdk/util-defaults-mode-browser": 3.279.0
+    "@aws-sdk/util-defaults-mode-node": 3.282.0
+    "@aws-sdk/util-endpoints": 3.272.0
+    "@aws-sdk/util-retry": 3.272.0
+    "@aws-sdk/util-stream-browser": 3.282.0
+    "@aws-sdk/util-stream-node": 3.282.0
+    "@aws-sdk/util-user-agent-browser": 3.282.0
+    "@aws-sdk/util-user-agent-node": 3.282.0
+    "@aws-sdk/util-utf8": 3.254.0
+    "@aws-sdk/util-waiter": 3.272.0
+    "@aws-sdk/xml-builder": 3.201.0
     fast-xml-parser: 4.1.2
-    tslib: ^2.5.0
-  checksum: 564fb486c47550e44abee25ebb98349418dc0c7d016695aeeb7fc08a0401353e0789f3191eb02825aee06e892d15c175434bf727d8e79a7af8c8deb9c08bf54d
+    tslib: ^2.3.1
+  checksum: 34b9c3515a01b75b170c5942fbfe2ac860efae5856dfeb831691a46f086f21a0d0f36fb05e7f8fe3bc4b84f476abd16ea6cd734592b6fb7a2d86aaaad54c4457
   languageName: node
   linkType: hard
 
 "@aws-sdk/client-sqs@npm:^3.208.0":
-  version: 3.299.0
-  resolution: "@aws-sdk/client-sqs@npm:3.299.0"
+  version: 3.272.0
+  resolution: "@aws-sdk/client-sqs@npm:3.272.0"
   dependencies:
     "@aws-crypto/sha256-browser": 3.0.0
     "@aws-crypto/sha256-js": 3.0.0
-    "@aws-sdk/client-sts": 3.299.0
-    "@aws-sdk/config-resolver": 3.299.0
-    "@aws-sdk/credential-provider-node": 3.299.0
-    "@aws-sdk/fetch-http-handler": 3.296.0
-    "@aws-sdk/hash-node": 3.296.0
-    "@aws-sdk/invalid-dependency": 3.296.0
-    "@aws-sdk/md5-js": 3.296.0
-    "@aws-sdk/middleware-content-length": 3.296.0
-    "@aws-sdk/middleware-endpoint": 3.299.0
-    "@aws-sdk/middleware-host-header": 3.296.0
-    "@aws-sdk/middleware-logger": 3.296.0
-    "@aws-sdk/middleware-recursion-detection": 3.296.0
-    "@aws-sdk/middleware-retry": 3.296.0
-    "@aws-sdk/middleware-sdk-sqs": 3.296.0
-    "@aws-sdk/middleware-serde": 3.296.0
-    "@aws-sdk/middleware-signing": 3.299.0
-    "@aws-sdk/middleware-stack": 3.296.0
-    "@aws-sdk/middleware-user-agent": 3.299.0
-    "@aws-sdk/node-config-provider": 3.296.0
-    "@aws-sdk/node-http-handler": 3.296.0
-    "@aws-sdk/protocol-http": 3.296.0
-    "@aws-sdk/smithy-client": 3.296.0
-    "@aws-sdk/types": 3.296.0
-    "@aws-sdk/url-parser": 3.296.0
-    "@aws-sdk/util-base64": 3.295.0
-    "@aws-sdk/util-body-length-browser": 3.295.0
-    "@aws-sdk/util-body-length-node": 3.295.0
-    "@aws-sdk/util-defaults-mode-browser": 3.296.0
-    "@aws-sdk/util-defaults-mode-node": 3.299.0
-    "@aws-sdk/util-endpoints": 3.296.0
-    "@aws-sdk/util-retry": 3.296.0
-    "@aws-sdk/util-user-agent-browser": 3.299.0
-    "@aws-sdk/util-user-agent-node": 3.299.0
-    "@aws-sdk/util-utf8": 3.295.0
+    "@aws-sdk/client-sts": 3.272.0
+    "@aws-sdk/config-resolver": 3.272.0
+    "@aws-sdk/credential-provider-node": 3.272.0
+    "@aws-sdk/fetch-http-handler": 3.272.0
+    "@aws-sdk/hash-node": 3.272.0
+    "@aws-sdk/invalid-dependency": 3.272.0
+    "@aws-sdk/md5-js": 3.272.0
+    "@aws-sdk/middleware-content-length": 3.282.0
+    "@aws-sdk/middleware-endpoint": 3.282.0
+    "@aws-sdk/middleware-host-header": 3.282.0
+    "@aws-sdk/middleware-logger": 3.272.0
+    "@aws-sdk/middleware-recursion-detection": 3.282.0
+    "@aws-sdk/middleware-retry": 3.282.0
+    "@aws-sdk/middleware-sdk-sqs": 3.272.0
+    "@aws-sdk/middleware-serde": 3.272.0
+    "@aws-sdk/middleware-signing": 3.282.0
+    "@aws-sdk/middleware-stack": 3.272.0
+    "@aws-sdk/middleware-user-agent": 3.282.0
+    "@aws-sdk/node-config-provider": 3.272.0
+    "@aws-sdk/node-http-handler": 3.282.0
+    "@aws-sdk/protocol-http": 3.282.0
+    "@aws-sdk/smithy-client": 3.279.0
+    "@aws-sdk/types": 3.272.0
+    "@aws-sdk/url-parser": 3.272.0
+    "@aws-sdk/util-base64": 3.208.0
+    "@aws-sdk/util-body-length-browser": 3.188.0
+    "@aws-sdk/util-body-length-node": 3.208.0
+    "@aws-sdk/util-defaults-mode-browser": 3.279.0
+    "@aws-sdk/util-defaults-mode-node": 3.282.0
+    "@aws-sdk/util-endpoints": 3.272.0
+    "@aws-sdk/util-retry": 3.272.0
+    "@aws-sdk/util-user-agent-browser": 3.282.0
+    "@aws-sdk/util-user-agent-node": 3.282.0
+    "@aws-sdk/util-utf8": 3.254.0
     fast-xml-parser: 4.1.2
-    tslib: ^2.5.0
-  checksum: a9e40735cfbef7beea646aa1047b0e629006b882b42bea61b129df415521ae5cb2e93c823d0117fb0deb38f43d7c239d4147e9268f3b78f7fd74c33634f8e7cf
+    tslib: ^2.3.1
+  checksum: 7188f5b769b98710624bf389475f5eb345fc20fb7078dc9c425c65803aa9006258ba32467ec71dd082832c3af0388ef6fa59aabb76b736eb97fe2f937082b86b
   languageName: node
   linkType: hard
 
@@ -739,6 +831,94 @@ __metadata:
   languageName: node
   linkType: hard
 
+"@aws-sdk/client-sts@npm:3.272.0":
+  version: 3.272.0
+  resolution: "@aws-sdk/client-sts@npm:3.272.0"
+  dependencies:
+    "@aws-crypto/sha256-browser": 3.0.0
+    "@aws-crypto/sha256-js": 3.0.0
+    "@aws-sdk/config-resolver": 3.272.0
+    "@aws-sdk/credential-provider-node": 3.272.0
+    "@aws-sdk/fetch-http-handler": 3.272.0
+    "@aws-sdk/hash-node": 3.272.0
+    "@aws-sdk/invalid-dependency": 3.272.0
+    "@aws-sdk/middleware-content-length": 3.272.0
+    "@aws-sdk/middleware-endpoint": 3.272.0
+    "@aws-sdk/middleware-host-header": 3.272.0
+    "@aws-sdk/middleware-logger": 3.272.0
+    "@aws-sdk/middleware-recursion-detection": 3.272.0
+    "@aws-sdk/middleware-retry": 3.272.0
+    "@aws-sdk/middleware-sdk-sts": 3.272.0
+    "@aws-sdk/middleware-serde": 3.272.0
+    "@aws-sdk/middleware-signing": 3.272.0
+    "@aws-sdk/middleware-stack": 3.272.0
+    "@aws-sdk/middleware-user-agent": 3.272.0
+    "@aws-sdk/node-config-provider": 3.272.0
+    "@aws-sdk/node-http-handler": 3.272.0
+    "@aws-sdk/protocol-http": 3.272.0
+    "@aws-sdk/smithy-client": 3.272.0
+    "@aws-sdk/types": 3.272.0
+    "@aws-sdk/url-parser": 3.272.0
+    "@aws-sdk/util-base64": 3.208.0
+    "@aws-sdk/util-body-length-browser": 3.188.0
+    "@aws-sdk/util-body-length-node": 3.208.0
+    "@aws-sdk/util-defaults-mode-browser": 3.272.0
+    "@aws-sdk/util-defaults-mode-node": 3.272.0
+    "@aws-sdk/util-endpoints": 3.272.0
+    "@aws-sdk/util-retry": 3.272.0
+    "@aws-sdk/util-user-agent-browser": 3.272.0
+    "@aws-sdk/util-user-agent-node": 3.272.0
+    "@aws-sdk/util-utf8": 3.254.0
+    fast-xml-parser: 4.1.2
+    tslib: ^2.3.1
+  checksum: 2e3083803a4d64de3148ef49b6dccb1a54d6766a8c60a2002cff32f005159d69d8323e50b7cb6055cb0bd595b8e8f2bc8ccd839ee9ca17c5db47fc6b63b10269
+  languageName: node
+  linkType: hard
+
+"@aws-sdk/client-sts@npm:3.282.0, @aws-sdk/client-sts@npm:^3.208.0":
+  version: 3.282.0
+  resolution: "@aws-sdk/client-sts@npm:3.282.0"
+  dependencies:
+    "@aws-crypto/sha256-browser": 3.0.0
+    "@aws-crypto/sha256-js": 3.0.0
+    "@aws-sdk/config-resolver": 3.299.0
+    "@aws-sdk/credential-provider-node": 3.299.0
+    "@aws-sdk/fetch-http-handler": 3.296.0
+    "@aws-sdk/hash-node": 3.296.0
+    "@aws-sdk/invalid-dependency": 3.296.0
+    "@aws-sdk/middleware-content-length": 3.296.0
+    "@aws-sdk/middleware-endpoint": 3.299.0
+    "@aws-sdk/middleware-host-header": 3.296.0
+    "@aws-sdk/middleware-logger": 3.296.0
+    "@aws-sdk/middleware-recursion-detection": 3.296.0
+    "@aws-sdk/middleware-retry": 3.296.0
+    "@aws-sdk/middleware-sdk-sts": 3.299.0
+    "@aws-sdk/middleware-serde": 3.296.0
+    "@aws-sdk/middleware-signing": 3.299.0
+    "@aws-sdk/middleware-stack": 3.296.0
+    "@aws-sdk/middleware-user-agent": 3.299.0
+    "@aws-sdk/node-config-provider": 3.296.0
+    "@aws-sdk/node-http-handler": 3.296.0
+    "@aws-sdk/protocol-http": 3.296.0
+    "@aws-sdk/smithy-client": 3.296.0
+    "@aws-sdk/types": 3.296.0
+    "@aws-sdk/url-parser": 3.296.0
+    "@aws-sdk/util-base64": 3.295.0
+    "@aws-sdk/util-body-length-browser": 3.295.0
+    "@aws-sdk/util-body-length-node": 3.295.0
+    "@aws-sdk/util-defaults-mode-browser": 3.296.0
+    "@aws-sdk/util-defaults-mode-node": 3.299.0
+    "@aws-sdk/util-endpoints": 3.296.0
+    "@aws-sdk/util-retry": 3.296.0
+    "@aws-sdk/util-user-agent-browser": 3.299.0
+    "@aws-sdk/util-user-agent-node": 3.299.0
+    "@aws-sdk/util-utf8": 3.295.0
+    fast-xml-parser: 4.1.2
+    tslib: ^2.5.0
+  checksum: 4a9160e0e79a3f5d39646d56dbd9a0cb52063164df42e88640019ca74e88e49f7c36ddb98beae537051eb0798d912e283262657bdf420c6640ed04783f2d3d72
+  languageName: node
+  linkType: hard
+
 "@aws-sdk/client-sts@npm:3.299.0, @aws-sdk/client-sts@npm:^3.208.0":
   version: 3.299.0
   resolution: "@aws-sdk/client-sts@npm:3.299.0"
@@ -783,6 +963,62 @@ __metadata:
   languageName: node
   linkType: hard
 
+"@aws-sdk/client-sts@npm:^3.208.0":
+  version: 3.276.0
+  resolution: "@aws-sdk/client-sts@npm:3.276.0"
+  dependencies:
+    "@aws-crypto/sha256-browser": 3.0.0
+    "@aws-crypto/sha256-js": 3.0.0
+    "@aws-sdk/config-resolver": 3.282.0
+    "@aws-sdk/credential-provider-node": 3.282.0
+    "@aws-sdk/fetch-http-handler": 3.282.0
+    "@aws-sdk/hash-node": 3.272.0
+    "@aws-sdk/invalid-dependency": 3.272.0
+    "@aws-sdk/middleware-content-length": 3.282.0
+    "@aws-sdk/middleware-endpoint": 3.282.0
+    "@aws-sdk/middleware-host-header": 3.282.0
+    "@aws-sdk/middleware-logger": 3.272.0
+    "@aws-sdk/middleware-recursion-detection": 3.282.0
+    "@aws-sdk/middleware-retry": 3.282.0
+    "@aws-sdk/middleware-sdk-sts": 3.282.0
+    "@aws-sdk/middleware-serde": 3.272.0
+    "@aws-sdk/middleware-signing": 3.282.0
+    "@aws-sdk/middleware-stack": 3.272.0
+    "@aws-sdk/middleware-user-agent": 3.282.0
+    "@aws-sdk/node-config-provider": 3.272.0
+    "@aws-sdk/node-http-handler": 3.282.0
+    "@aws-sdk/protocol-http": 3.282.0
+    "@aws-sdk/smithy-client": 3.279.0
+    "@aws-sdk/types": 3.272.0
+    "@aws-sdk/url-parser": 3.272.0
+    "@aws-sdk/util-base64": 3.208.0
+    "@aws-sdk/util-body-length-browser": 3.188.0
+    "@aws-sdk/util-body-length-node": 3.208.0
+    "@aws-sdk/util-defaults-mode-browser": 3.279.0
+    "@aws-sdk/util-defaults-mode-node": 3.282.0
+    "@aws-sdk/util-endpoints": 3.272.0
+    "@aws-sdk/util-retry": 3.272.0
+    "@aws-sdk/util-user-agent-browser": 3.282.0
+    "@aws-sdk/util-user-agent-node": 3.282.0
+    "@aws-sdk/util-utf8": 3.254.0
+    fast-xml-parser: 4.1.2
+    tslib: ^2.3.1
+  checksum: 5af24417f7ef2dbebe6b0c0aa545eeb809e92136bce2b1e7dd07de1159f2308c2d673c3b136440e4137ce7524cbdabe50e80d7ca6f8635a3d9dcd2983532a9e7
+  languageName: node
+  linkType: hard
+
+"@aws-sdk/config-resolver@npm:3.282.0":
+  version: 3.282.0
+  resolution: "@aws-sdk/config-resolver@npm:3.282.0"
+  dependencies:
+    "@aws-sdk/types": 3.296.0
+    "@aws-sdk/util-config-provider": 3.295.0
+    "@aws-sdk/util-middleware": 3.296.0
+    tslib: ^2.5.0
+  checksum: 2fc2bd424a3b24cabf1df549b6102a47657ddf77f6d81cf2d477fd7eec407071febc5ec5e21384903104526b753c71777106c24dfdfd055e2b8cd810d7d50730
+  languageName: node
+  linkType: hard
+
 "@aws-sdk/config-resolver@npm:3.299.0":
   version: 3.299.0
   resolution: "@aws-sdk/config-resolver@npm:3.299.0"
@@ -795,6 +1031,30 @@ __metadata:
   languageName: node
   linkType: hard
 
+"@aws-sdk/credential-provider-cognito-identity@npm:3.272.0":
+  version: 3.272.0
+  resolution: "@aws-sdk/credential-provider-cognito-identity@npm:3.272.0"
+  dependencies:
+    "@aws-sdk/client-cognito-identity": 3.272.0
+    "@aws-sdk/property-provider": 3.272.0
+    "@aws-sdk/types": 3.272.0
+    tslib: ^2.3.1
+  checksum: ba19883f08b8c4625d53a9c243eb8a831f51d7764157d86fc9a0343cd02c5fbd41923a21b5579c718c3b490a97eacc83fe398f5f920dcbd3ce41a3326959b652
+  languageName: node
+  linkType: hard
+
+"@aws-sdk/credential-provider-cognito-identity@npm:3.282.0":
+  version: 3.282.0
+  resolution: "@aws-sdk/credential-provider-cognito-identity@npm:3.282.0"
+  dependencies:
+    "@aws-sdk/client-cognito-identity": 3.299.0
+    "@aws-sdk/property-provider": 3.296.0
+    "@aws-sdk/types": 3.296.0
+    tslib: ^2.5.0
+  checksum: 03a1719599fa72cd42677a6b59cdb22285b0b27353489c9b04ddafc0a61d3cdd2206f90e456c2e162fb8b85f7d8214f25b774368624fa087dcd42f6ef187c8e6
+  languageName: node
+  linkType: hard
+
 "@aws-sdk/credential-provider-cognito-identity@npm:3.299.0":
   version: 3.299.0
   resolution: "@aws-sdk/credential-provider-cognito-identity@npm:3.299.0"
@@ -904,24 +1164,25 @@ __metadata:
   linkType: hard
 
 "@aws-sdk/credential-providers@npm:^3.208.0":
-  version: 3.299.0
-  resolution: "@aws-sdk/credential-providers@npm:3.299.0"
+  version: 3.272.0
+  resolution: "@aws-sdk/credential-providers@npm:3.272.0"
   dependencies:
-    "@aws-sdk/client-cognito-identity": 3.299.0
-    "@aws-sdk/client-sso": 3.299.0
-    "@aws-sdk/client-sts": 3.299.0
-    "@aws-sdk/credential-provider-cognito-identity": 3.299.0
-    "@aws-sdk/credential-provider-env": 3.296.0
-    "@aws-sdk/credential-provider-imds": 3.296.0
-    "@aws-sdk/credential-provider-ini": 3.299.0
-    "@aws-sdk/credential-provider-node": 3.299.0
-    "@aws-sdk/credential-provider-process": 3.296.0
-    "@aws-sdk/credential-provider-sso": 3.299.0
-    "@aws-sdk/credential-provider-web-identity": 3.296.0
-    "@aws-sdk/property-provider": 3.296.0
-    "@aws-sdk/types": 3.296.0
-    tslib: ^2.5.0
-  checksum: 0c1f49d6e057925f13a1a7028bb4fee124a1ec08d16fe5616aa7272007d8a9e70cd292726628a95d17a7d7099c91b88d94712faa2751da34bebee574f6e2ee4d
+    "@aws-sdk/client-cognito-identity": 3.272.0
+    "@aws-sdk/client-sso": 3.272.0
+    "@aws-sdk/client-sts": 3.272.0
+    "@aws-sdk/credential-provider-cognito-identity": 3.272.0
+    "@aws-sdk/credential-provider-env": 3.272.0
+    "@aws-sdk/credential-provider-imds": 3.272.0
+    "@aws-sdk/credential-provider-ini": 3.282.0
+    "@aws-sdk/credential-provider-node": 3.282.0
+    "@aws-sdk/credential-provider-process": 3.272.0
+    "@aws-sdk/credential-provider-sso": 3.282.0
+    "@aws-sdk/credential-provider-web-identity": 3.272.0
+    "@aws-sdk/property-provider": 3.272.0
+    "@aws-sdk/shared-ini-file-loader": 3.272.0
+    "@aws-sdk/types": 3.272.0
+    tslib: ^2.3.1
+  checksum: ce311afb81267bc984a9dabffb3df1689cd63c8ed75010163aced4855bf96399a225ae594b494cfcfbb970e9bfe0461576d82a5695065d9e4ca0c82755edd52b
   languageName: node
   linkType: hard
 
@@ -1047,8 +1308,8 @@ __metadata:
   linkType: hard
 
 "@aws-sdk/lib-storage@npm:^3.208.0":
-  version: 3.299.0
-  resolution: "@aws-sdk/lib-storage@npm:3.299.0"
+  version: 3.272.0
+  resolution: "@aws-sdk/lib-storage@npm:3.272.0"
   dependencies:
     "@aws-sdk/middleware-endpoint": 3.299.0
     "@aws-sdk/smithy-client": 3.296.0
@@ -1059,7 +1320,7 @@ __metadata:
   peerDependencies:
     "@aws-sdk/abort-controller": ^3.0.0
     "@aws-sdk/client-s3": ^3.0.0
-  checksum: bbf180386c03ac4fb78c65c7b476dbb6bb5c81a4d8013e8c216710b6654642e89d4cd6dc8fe3383b42c285c098ca8f325199b58efdc13b5278ed6ce011b28331
+  checksum: 7c4f25fec63d60ade365062fbd1cf9807593268f3b0354ea22b5e06619e443f5421da920255875455d84fc19900d5472fa5e92a5bd46c1f3be148da67afa58f8
   languageName: node
   linkType: hard
 
@@ -3342,7 +3603,7 @@ __metadata:
   languageName: node
   linkType: hard
 
-"@babel/runtime@npm:^7.0.0, @babel/runtime@npm:^7.1.2, @babel/runtime@npm:^7.10.1, @babel/runtime@npm:^7.12.1, @babel/runtime@npm:^7.12.5, @babel/runtime@npm:^7.14.6, @babel/runtime@npm:^7.15.4, @babel/runtime@npm:^7.18.3, @babel/runtime@npm:^7.18.6, @babel/runtime@npm:^7.2.0, @babel/runtime@npm:^7.20.1, @babel/runtime@npm:^7.20.7, @babel/runtime@npm:^7.3.1, @babel/runtime@npm:^7.4.4, @babel/runtime@npm:^7.5.5, @babel/runtime@npm:^7.6.0, @babel/runtime@npm:^7.7.6, @babel/runtime@npm:^7.8.3, @babel/runtime@npm:^7.8.4, @babel/runtime@npm:^7.8.7, @babel/runtime@npm:^7.9.2":
+"@babel/runtime@npm:^7.0.0, @babel/runtime@npm:^7.1.2, @babel/runtime@npm:^7.10.1, @babel/runtime@npm:^7.12.1, @babel/runtime@npm:^7.12.5, @babel/runtime@npm:^7.14.6, @babel/runtime@npm:^7.15.4, @babel/runtime@npm:^7.18.6, @babel/runtime@npm:^7.2.0, @babel/runtime@npm:^7.20.1, @babel/runtime@npm:^7.20.7, @babel/runtime@npm:^7.3.1, @babel/runtime@npm:^7.4.4, @babel/runtime@npm:^7.5.5, @babel/runtime@npm:^7.6.0, @babel/runtime@npm:^7.7.6, @babel/runtime@npm:^7.8.3, @babel/runtime@npm:^7.8.4, @babel/runtime@npm:^7.8.7, @babel/runtime@npm:^7.9.2":
   version: 7.20.13
   resolution: "@babel/runtime@npm:7.20.13"
   dependencies:
@@ -3351,6 +3612,15 @@ __metadata:
   languageName: node
   linkType: hard
 
+"@babel/runtime@npm:^7.18.3":
+  version: 7.21.0
+  resolution: "@babel/runtime@npm:7.21.0"
+  dependencies:
+    regenerator-runtime: ^0.13.11
+  checksum: 7b33e25bfa9e0e1b9e8828bb61b2d32bdd46b41b07ba7cb43319ad08efc6fda8eb89445193e67d6541814627df0ca59122c0ea795e412b99c5183a0540d338ab
+  languageName: node
+  linkType: hard
+
 "@babel/template@npm:^7.18.10, @babel/template@npm:^7.18.6, @babel/template@npm:^7.3.3":
   version: 7.18.10
   resolution: "@babel/template@npm:7.18.10"
@@ -14807,6 +15077,13 @@ __metadata:
   languageName: node
   linkType: hard
 
+"@tanstack/query-core@npm:4.24.9":
+  version: 4.24.9
+  resolution: "@tanstack/query-core@npm:4.24.9"
+  checksum: 7b84e960d82c046c9eef6083cbc13b21c2ed8552fe8a5f092a66ca2586af66b770ca71ad838135ef49ac8b990e5f85d34a1d8b8de13fffb3abb0fb780a64a532
+  languageName: node
+  linkType: hard
+
 "@tanstack/query-core@npm:4.27.0":
   version: 4.27.0
   resolution: "@tanstack/query-core@npm:4.27.0"
@@ -14815,10 +15092,10 @@ __metadata:
   linkType: hard
 
 "@tanstack/react-query@npm:^4.1.3":
-  version: 4.28.0
-  resolution: "@tanstack/react-query@npm:4.28.0"
+  version: 4.24.9
+  resolution: "@tanstack/react-query@npm:4.24.9"
   dependencies:
-    "@tanstack/query-core": 4.27.0
+    "@tanstack/query-core": 4.24.9
     use-sync-external-store: ^1.2.0
   peerDependencies:
     react: ^16.8.0 || ^17.0.0 || ^18.0.0
@@ -14829,7 +15106,7 @@ __metadata:
       optional: true
     react-native:
       optional: true
-  checksum: 7baa70d22b55cfa22f8a1d92ba9f8379c5436ee81fce3f0e7df4a8c29bb26bfef4a83759cf10f752b40ae2940099fcce88ce91a773240f4999ae91136980c6e3
+  checksum: 409c945c5043d11fa2f3c219254df5b0505bdf7d9dc94821f5db495d87a38fe27e0a373144446cef42fc829d1449a64e3fa873adf37e8abe15562e5832d59516
   languageName: node
   linkType: hard
 
@@ -20411,6 +20688,13 @@ __metadata:
   linkType: hard
 
 "content-type@npm:^1.0.4":
+  version: 1.0.5
+  resolution: "content-type@npm:1.0.5"
+  checksum: 566271e0a251642254cde0f845f9dd4f9856e52d988f4eb0d0dcffbb7a1f8ec98de7a5215fc628f3bce30fe2fb6fd2bc064b562d721658c59b544e2d34ea2766
+  languageName: node
+  linkType: hard
+
+"content-type@npm:~1.0.4":
   version: 1.0.4
   resolution: "content-type@npm:1.0.4"
   checksum: 3d93585fda985d1554eca5ebd251994327608d2e200978fdbfba21c0c679914d5faf266d17027de44b34a72c7b0745b18584ecccaa7e1fdfb6a68ac7114f12e0
@@ -32116,11 +32400,11 @@ __metadata:
   linkType: hard
 
 "openapi3-ts@npm:^3.1.2":
-  version: 3.1.2
-  resolution: "openapi3-ts@npm:3.1.2"
+  version: 3.2.0
+  resolution: "openapi3-ts@npm:3.2.0"
   dependencies:
-    yaml: ^2.1.3
-  checksum: 77e5064ea9bff119ba8d8398a90246ae99174d6c23b2ed68355bb48be3243b6f4f0041a3fdcd9dba5ffe6ace786a8041d86d8a4049d65d2d40cd4bfca5bba459
+    yaml: ^2.2.1
+  checksum: 8796a29a1363bc892ba1acb3ddffd9e6b80e8f83cbfad4cd507262e957317139cac2528ab4b14c1b30bf350ebc9cc4c43ad32a89da4d7c4b85f7e815ffba3ebe
   languageName: node
   linkType: hard
 
@@ -38649,6 +38933,13 @@ __metadata:
   languageName: node
   linkType: hard
 
+"ts-log@npm:^2.1.4":
+  version: 2.2.5
+  resolution: "ts-log@npm:2.2.5"
+  checksum: 28f78ab15b8555d56c089dbc243327d8ce4331219956242a29fc4cb3bad6bb0cb8234dd17a292381a1b1dba99a7e4849a2181b2e1a303e8247e9f4ca4e284f2d
+  languageName: node
+  linkType: hard
+
 "ts-log@npm:^2.1.4, ts-log@npm:^2.2.3":
   version: 2.2.5
   resolution: "ts-log@npm:2.2.5"
@@ -38656,6 +38947,13 @@ __metadata:
   languageName: node
   linkType: hard
 
+"ts-log@npm:^2.2.3":
+  version: 2.2.3
+  resolution: "ts-log@npm:2.2.3"
+  checksum: 8aa34a2724d7915ddc6de8d0c27eb48f67206b52c42656f1ea2a7ffb080fa664db5fb22b42bd3c72b5b95cc6eb4612196b7d1e28f4bc146191ebc2a9683af548
+  languageName: node
+  linkType: hard
+
 "ts-morph@npm:^17.0.0":
   version: 17.0.1
   resolution: "ts-morph@npm:17.0.1"
@@ -40618,6 +40916,13 @@ __metadata:
   languageName: node
   linkType: hard
 
+"yaml@npm:^2.2.1":
+  version: 2.2.1
+  resolution: "yaml@npm:2.2.1"
+  checksum: 84f68cbe462d5da4e7ded4a8bded949ffa912bc264472e5a684c3d45b22d8f73a3019963a32164023bdf3d83cfb6f5b58ff7b2b10ef5b717c630f40bd6369a23
+  languageName: node
+  linkType: hard
+
 "yargs-parser@npm:^18.1.2, yargs-parser@npm:^18.1.3":
   version: 18.1.3
   resolution: "yargs-parser@npm:18.1.3"

From b76999c4dfba21b155811068c84113dc50842618 Mon Sep 17 00:00:00 2001
From: Aramis Sennyey <sennyeya@amazon.com>
Date: Wed, 22 Feb 2023 12:54:33 -0500
Subject: [PATCH 09/61] Update yarn file and revert createRouter.ts changes.

Signed-off-by: Aramis Sennyey <sennyeya@amazon.com>
---
 .../src/service/createRouter.ts               |  28 +++-
 yarn.lock                                     | 151 ++++++++++++++----
 2 files changed, 141 insertions(+), 38 deletions(-)

diff --git a/plugins/catalog-backend/src/service/createRouter.ts b/plugins/catalog-backend/src/service/createRouter.ts
index 5da996546d..99e9c6b0df 100644
--- a/plugins/catalog-backend/src/service/createRouter.ts
+++ b/plugins/catalog-backend/src/service/createRouter.ts
@@ -133,6 +133,26 @@ export async function createRouter(
         // TODO(freben): encode the pageInfo in the response
         res.json(entities);
       })
+      .get('/entities/by-query', async (req, res) => {
+        const { items, pageInfo, totalItems } =
+          await entitiesCatalog.queryEntities({
+            ...parseQueryEntitiesParams(req.query),
+            authorizationToken: getBearerToken(req.header('authorization')),
+          });
+
+        res.json({
+          items,
+          totalItems,
+          pageInfo: {
+            ...(pageInfo.nextCursor && {
+              nextCursor: encodeCursor(pageInfo.nextCursor),
+            }),
+            ...(pageInfo.prevCursor && {
+              prevCursor: encodeCursor(pageInfo.prevCursor),
+            }),
+          },
+        });
+      })
       .get('/entities/by-uid/:uid', async (req, res) => {
         const { uid } = req.params;
         const { entities } = await entitiesCatalog.entities({
@@ -187,9 +207,7 @@ export async function createRouter(
           fields: parseEntityTransformParams(req.query, request.fields),
           authorizationToken: token,
         });
-        // These responses are interacting weirdly with the underlying interface passed to them,
-        //  we just need to re-load the TS server's short term memory.
-        res.status(200).json({ ...response });
+        res.status(200).json(response);
       })
       .get('/entity-facets', async (req, res) => {
         const response = await entitiesCatalog.facets({
@@ -197,9 +215,7 @@ export async function createRouter(
           facets: parseEntityFacetParams(req.query),
           authorizationToken: getBearerToken(req.header('authorization')),
         });
-        // These responses are interacting weirdly with the underlying interface passed to them,
-        //  we just need to re-load the TS server's short term memory.
-        res.status(200).json({ ...response });
+        res.status(200).json(response);
       });
   }
 
diff --git a/yarn.lock b/yarn.lock
index 8152fac354..fd223f444f 100644
--- a/yarn.lock
+++ b/yarn.lock
@@ -520,7 +520,7 @@ __metadata:
   dependencies:
     "@aws-crypto/sha256-browser": 3.0.0
     "@aws-crypto/sha256-js": 3.0.0
-    "@aws-sdk/client-sts": 3.272.0
+    "@aws-sdk/client-sts": 3.276.0
     "@aws-sdk/config-resolver": 3.272.0
     "@aws-sdk/credential-provider-node": 3.272.0
     "@aws-sdk/fetch-http-handler": 3.272.0
@@ -553,7 +553,50 @@ __metadata:
     "@aws-sdk/util-user-agent-node": 3.282.0
     "@aws-sdk/util-utf8": 3.254.0
     tslib: ^2.3.1
-  checksum: fd17c705b2de99fd1570239b62032525380b5e17799fc15f720196a488889fa10bbccd01952d5694ca8c20249d8a808de86de07d5a1b0d21486964a70d9b6d4d
+  checksum: ff79c1c727d956e03510307b001c24534d522b327871b2b0a1d39120e6d6717e17d7b9c2b7a6d28c3e5c3f41cd8ff28e5150ddd1fda9bff0c239fdfef0a78e00
+  languageName: node
+  linkType: hard
+
+"@aws-sdk/client-cognito-identity@npm:3.276.0":
+  version: 3.276.0
+  resolution: "@aws-sdk/client-cognito-identity@npm:3.276.0"
+  dependencies:
+    "@aws-crypto/sha256-browser": 3.0.0
+    "@aws-crypto/sha256-js": 3.0.0
+    "@aws-sdk/client-sts": 3.276.0
+    "@aws-sdk/config-resolver": 3.272.0
+    "@aws-sdk/credential-provider-node": 3.272.0
+    "@aws-sdk/fetch-http-handler": 3.272.0
+    "@aws-sdk/hash-node": 3.272.0
+    "@aws-sdk/invalid-dependency": 3.272.0
+    "@aws-sdk/middleware-content-length": 3.282.0
+    "@aws-sdk/middleware-endpoint": 3.282.0
+    "@aws-sdk/middleware-host-header": 3.282.0
+    "@aws-sdk/middleware-logger": 3.272.0
+    "@aws-sdk/middleware-recursion-detection": 3.282.0
+    "@aws-sdk/middleware-retry": 3.282.0
+    "@aws-sdk/middleware-serde": 3.272.0
+    "@aws-sdk/middleware-signing": 3.282.0
+    "@aws-sdk/middleware-stack": 3.272.0
+    "@aws-sdk/middleware-user-agent": 3.282.0
+    "@aws-sdk/node-config-provider": 3.272.0
+    "@aws-sdk/node-http-handler": 3.282.0
+    "@aws-sdk/protocol-http": 3.282.0
+    "@aws-sdk/smithy-client": 3.279.0
+    "@aws-sdk/types": 3.272.0
+    "@aws-sdk/url-parser": 3.272.0
+    "@aws-sdk/util-base64": 3.208.0
+    "@aws-sdk/util-body-length-browser": 3.188.0
+    "@aws-sdk/util-body-length-node": 3.208.0
+    "@aws-sdk/util-defaults-mode-browser": 3.279.0
+    "@aws-sdk/util-defaults-mode-node": 3.282.0
+    "@aws-sdk/util-endpoints": 3.272.0
+    "@aws-sdk/util-retry": 3.272.0
+    "@aws-sdk/util-user-agent-browser": 3.282.0
+    "@aws-sdk/util-user-agent-node": 3.282.0
+    "@aws-sdk/util-utf8": 3.254.0
+    tslib: ^2.3.1
+  checksum: ff79c1c727d956e03510307b001c24534d522b327871b2b0a1d39120e6d6717e17d7b9c2b7a6d28c3e5c3f41cd8ff28e5150ddd1fda9bff0c239fdfef0a78e00
   languageName: node
   linkType: hard
 
@@ -644,13 +687,13 @@ __metadata:
   linkType: hard
 
 "@aws-sdk/client-s3@npm:^3.208.0":
-  version: 3.272.0
-  resolution: "@aws-sdk/client-s3@npm:3.272.0"
+  version: 3.276.0
+  resolution: "@aws-sdk/client-s3@npm:3.276.0"
   dependencies:
     "@aws-crypto/sha1-browser": 3.0.0
     "@aws-crypto/sha256-browser": 3.0.0
     "@aws-crypto/sha256-js": 3.0.0
-    "@aws-sdk/client-sts": 3.272.0
+    "@aws-sdk/client-sts": 3.276.0
     "@aws-sdk/config-resolver": 3.272.0
     "@aws-sdk/credential-provider-node": 3.272.0
     "@aws-sdk/eventstream-serde-browser": 3.272.0
@@ -701,17 +744,17 @@ __metadata:
     "@aws-sdk/xml-builder": 3.201.0
     fast-xml-parser: 4.1.2
     tslib: ^2.3.1
-  checksum: 34b9c3515a01b75b170c5942fbfe2ac860efae5856dfeb831691a46f086f21a0d0f36fb05e7f8fe3bc4b84f476abd16ea6cd734592b6fb7a2d86aaaad54c4457
+  checksum: f7f475b92c0cff800536fb910bb6ffefcee6e650208f1791ea64c95bcbb6c63ef7a55e3f72af44e2e730a53865857ac4b974f00cb7da1e369d742cc95e33f02a
   languageName: node
   linkType: hard
 
 "@aws-sdk/client-sqs@npm:^3.208.0":
-  version: 3.272.0
-  resolution: "@aws-sdk/client-sqs@npm:3.272.0"
+  version: 3.276.0
+  resolution: "@aws-sdk/client-sqs@npm:3.276.0"
   dependencies:
     "@aws-crypto/sha256-browser": 3.0.0
     "@aws-crypto/sha256-js": 3.0.0
-    "@aws-sdk/client-sts": 3.272.0
+    "@aws-sdk/client-sts": 3.276.0
     "@aws-sdk/config-resolver": 3.272.0
     "@aws-sdk/credential-provider-node": 3.272.0
     "@aws-sdk/fetch-http-handler": 3.272.0
@@ -747,7 +790,7 @@ __metadata:
     "@aws-sdk/util-utf8": 3.254.0
     fast-xml-parser: 4.1.2
     tslib: ^2.3.1
-  checksum: 7188f5b769b98710624bf389475f5eb345fc20fb7078dc9c425c65803aa9006258ba32467ec71dd082832c3af0388ef6fa59aabb76b736eb97fe2f937082b86b
+  checksum: 88139fde34fa6348e841de13fce5e68b2dfb735c5358c959f9956a8c918048bde8b1ff701e8e701807af5f67f6df129056986b62a7e07096cc7097f3491d36b8
   languageName: node
   linkType: hard
 
@@ -875,6 +918,50 @@ __metadata:
   languageName: node
   linkType: hard
 
+"@aws-sdk/client-sts@npm:3.276.0, @aws-sdk/client-sts@npm:^3.208.0":
+  version: 3.276.0
+  resolution: "@aws-sdk/client-sts@npm:3.276.0"
+  dependencies:
+    "@aws-crypto/sha256-browser": 3.0.0
+    "@aws-crypto/sha256-js": 3.0.0
+    "@aws-sdk/config-resolver": 3.282.0
+    "@aws-sdk/credential-provider-node": 3.282.0
+    "@aws-sdk/fetch-http-handler": 3.282.0
+    "@aws-sdk/hash-node": 3.272.0
+    "@aws-sdk/invalid-dependency": 3.272.0
+    "@aws-sdk/middleware-content-length": 3.282.0
+    "@aws-sdk/middleware-endpoint": 3.282.0
+    "@aws-sdk/middleware-host-header": 3.282.0
+    "@aws-sdk/middleware-logger": 3.272.0
+    "@aws-sdk/middleware-recursion-detection": 3.282.0
+    "@aws-sdk/middleware-retry": 3.282.0
+    "@aws-sdk/middleware-sdk-sts": 3.282.0
+    "@aws-sdk/middleware-serde": 3.272.0
+    "@aws-sdk/middleware-signing": 3.282.0
+    "@aws-sdk/middleware-stack": 3.272.0
+    "@aws-sdk/middleware-user-agent": 3.282.0
+    "@aws-sdk/node-config-provider": 3.272.0
+    "@aws-sdk/node-http-handler": 3.282.0
+    "@aws-sdk/protocol-http": 3.282.0
+    "@aws-sdk/smithy-client": 3.279.0
+    "@aws-sdk/types": 3.272.0
+    "@aws-sdk/url-parser": 3.272.0
+    "@aws-sdk/util-base64": 3.208.0
+    "@aws-sdk/util-body-length-browser": 3.188.0
+    "@aws-sdk/util-body-length-node": 3.208.0
+    "@aws-sdk/util-defaults-mode-browser": 3.279.0
+    "@aws-sdk/util-defaults-mode-node": 3.282.0
+    "@aws-sdk/util-endpoints": 3.272.0
+    "@aws-sdk/util-retry": 3.272.0
+    "@aws-sdk/util-user-agent-browser": 3.282.0
+    "@aws-sdk/util-user-agent-node": 3.282.0
+    "@aws-sdk/util-utf8": 3.254.0
+    fast-xml-parser: 4.1.2
+    tslib: ^2.3.1
+  checksum: 5af24417f7ef2dbebe6b0c0aa545eeb809e92136bce2b1e7dd07de1159f2308c2d673c3b136440e4137ce7524cbdabe50e80d7ca6f8635a3d9dcd2983532a9e7
+  languageName: node
+  linkType: hard
+
 "@aws-sdk/client-sts@npm:3.282.0, @aws-sdk/client-sts@npm:^3.208.0":
   version: 3.282.0
   resolution: "@aws-sdk/client-sts@npm:3.282.0"
@@ -1031,15 +1118,15 @@ __metadata:
   languageName: node
   linkType: hard
 
-"@aws-sdk/credential-provider-cognito-identity@npm:3.272.0":
-  version: 3.272.0
-  resolution: "@aws-sdk/credential-provider-cognito-identity@npm:3.272.0"
+"@aws-sdk/credential-provider-cognito-identity@npm:3.276.0":
+  version: 3.276.0
+  resolution: "@aws-sdk/credential-provider-cognito-identity@npm:3.276.0"
   dependencies:
-    "@aws-sdk/client-cognito-identity": 3.272.0
+    "@aws-sdk/client-cognito-identity": 3.276.0
     "@aws-sdk/property-provider": 3.272.0
     "@aws-sdk/types": 3.272.0
     tslib: ^2.3.1
-  checksum: ba19883f08b8c4625d53a9c243eb8a831f51d7764157d86fc9a0343cd02c5fbd41923a21b5579c718c3b490a97eacc83fe398f5f920dcbd3ce41a3326959b652
+  checksum: 2d255475f08beeccd000745b2f2c46553559fd6fe15c0ea9960956655535fb927df9ec3431cf743b80f9a460d033ede7e1c47e91aff44956559a70c5f43f7bab
   languageName: node
   linkType: hard
 
@@ -1164,13 +1251,13 @@ __metadata:
   linkType: hard
 
 "@aws-sdk/credential-providers@npm:^3.208.0":
-  version: 3.272.0
-  resolution: "@aws-sdk/credential-providers@npm:3.272.0"
+  version: 3.276.0
+  resolution: "@aws-sdk/credential-providers@npm:3.276.0"
   dependencies:
-    "@aws-sdk/client-cognito-identity": 3.272.0
+    "@aws-sdk/client-cognito-identity": 3.276.0
     "@aws-sdk/client-sso": 3.272.0
-    "@aws-sdk/client-sts": 3.272.0
-    "@aws-sdk/credential-provider-cognito-identity": 3.272.0
+    "@aws-sdk/client-sts": 3.276.0
+    "@aws-sdk/credential-provider-cognito-identity": 3.276.0
     "@aws-sdk/credential-provider-env": 3.272.0
     "@aws-sdk/credential-provider-imds": 3.272.0
     "@aws-sdk/credential-provider-ini": 3.282.0
@@ -1182,7 +1269,7 @@ __metadata:
     "@aws-sdk/shared-ini-file-loader": 3.272.0
     "@aws-sdk/types": 3.272.0
     tslib: ^2.3.1
-  checksum: ce311afb81267bc984a9dabffb3df1689cd63c8ed75010163aced4855bf96399a225ae594b494cfcfbb970e9bfe0461576d82a5695065d9e4ca0c82755edd52b
+  checksum: 825fb0feda57ef98cc11ab3febc2a337161193dfa24bcc31ad2b47ecb4af564b3b5a5a0d9c17fd1a3ec118321d21fc515948980ba50c323e21ed79905c13dfe4
   languageName: node
   linkType: hard
 
@@ -1308,8 +1395,8 @@ __metadata:
   linkType: hard
 
 "@aws-sdk/lib-storage@npm:^3.208.0":
-  version: 3.272.0
-  resolution: "@aws-sdk/lib-storage@npm:3.272.0"
+  version: 3.276.0
+  resolution: "@aws-sdk/lib-storage@npm:3.276.0"
   dependencies:
     "@aws-sdk/middleware-endpoint": 3.299.0
     "@aws-sdk/smithy-client": 3.296.0
@@ -1320,7 +1407,7 @@ __metadata:
   peerDependencies:
     "@aws-sdk/abort-controller": ^3.0.0
     "@aws-sdk/client-s3": ^3.0.0
-  checksum: 7c4f25fec63d60ade365062fbd1cf9807593268f3b0354ea22b5e06619e443f5421da920255875455d84fc19900d5472fa5e92a5bd46c1f3be148da67afa58f8
+  checksum: 1e34d3569c8cf2f7c42efdd7966a9faea64bf49f4fe1fcb0ff30ed86670a5ba2361bb14279e7dc1bc110a1ff9e5cec3551bc8a56b3c9c4d19f98ff4842a8de19
   languageName: node
   linkType: hard
 
@@ -15077,10 +15164,10 @@ __metadata:
   languageName: node
   linkType: hard
 
-"@tanstack/query-core@npm:4.24.9":
-  version: 4.24.9
-  resolution: "@tanstack/query-core@npm:4.24.9"
-  checksum: 7b84e960d82c046c9eef6083cbc13b21c2ed8552fe8a5f092a66ca2586af66b770ca71ad838135ef49ac8b990e5f85d34a1d8b8de13fffb3abb0fb780a64a532
+"@tanstack/query-core@npm:4.24.10":
+  version: 4.24.10
+  resolution: "@tanstack/query-core@npm:4.24.10"
+  checksum: 8268b9dca4a2ed39f8575976d8a3e2f839bb6f4fb821dc00ba8e2aeffffe2f73e23344bcc24b9cb6dae9dbfe3ba2b14c76a1e0a38b4064c83beb9aa607fd94bc
   languageName: node
   linkType: hard
 
@@ -15092,10 +15179,10 @@ __metadata:
   linkType: hard
 
 "@tanstack/react-query@npm:^4.1.3":
-  version: 4.24.9
-  resolution: "@tanstack/react-query@npm:4.24.9"
+  version: 4.24.10
+  resolution: "@tanstack/react-query@npm:4.24.10"
   dependencies:
-    "@tanstack/query-core": 4.24.9
+    "@tanstack/query-core": 4.24.10
     use-sync-external-store: ^1.2.0
   peerDependencies:
     react: ^16.8.0 || ^17.0.0 || ^18.0.0
@@ -15106,7 +15193,7 @@ __metadata:
       optional: true
     react-native:
       optional: true
-  checksum: 409c945c5043d11fa2f3c219254df5b0505bdf7d9dc94821f5db495d87a38fe27e0a373144446cef42fc829d1449a64e3fa873adf37e8abe15562e5832d59516
+  checksum: 576a2c73e98cf6a3c9584283989383d5ac63b01efe546cc7580ec7b1edf0c0cb8958a3071778cb0af908f5269d45c7516fa388e5f856e37f5b2d3c6110974cbe
   languageName: node
   linkType: hard
 

From 8eda7722a3d18dc2c679433573055e5003d53bfc Mon Sep 17 00:00:00 2001
From: Aramis Sennyey <sennyeya@amazon.com>
Date: Wed, 22 Feb 2023 15:30:50 -0500
Subject: [PATCH 10/61] Updating definitions to standardize to express type
 definitions.

Signed-off-by: Aramis Sennyey <sennyeya@amazon.com>
---
 plugins/catalog-backend/openapi.yaml          |  49 +++
 .../src/service/schema/openapi.ts             |  83 +++-
 plugins/openapi-router-common/package.json    |   2 +-
 plugins/openapi-router-common/src/example.ts  |  41 ++
 plugins/openapi-router-common/src/router.ts   | 359 +-----------------
 .../src/schema/petstore.ts                    | 181 +++++++++
 .../src/standaloneServer.ts                   |   2 +-
 .../openapi-router-common/src/types/common.ts |  36 +-
 .../src/types/express.ts                      |  86 +++++
 .../src/types/requests.ts                     |  14 +-
 .../src/types/response.ts                     |  14 +-
 yarn.lock                                     |   4 +-
 12 files changed, 518 insertions(+), 353 deletions(-)
 create mode 100644 plugins/openapi-router-common/src/example.ts
 create mode 100644 plugins/openapi-router-common/src/schema/petstore.ts
 create mode 100644 plugins/openapi-router-common/src/types/express.ts

diff --git a/plugins/catalog-backend/openapi.yaml b/plugins/catalog-backend/openapi.yaml
index 037b4633b0..5feacb8599 100644
--- a/plugins/catalog-backend/openapi.yaml
+++ b/plugins/catalog-backend/openapi.yaml
@@ -480,6 +480,28 @@ components:
             - message
             - name
       description: The serialized form of an Error.
+    EntitiesQueryResponse:
+      type: object
+      properties:
+        items:
+          type: array
+          items:
+            - $ref: '#/components/schemas/Entity'
+          description: |-
+            The list of entities paginated by a specific filter.
+        totalItems:
+          type: number
+        pageInfo:
+          type: object
+          properties:
+            nextCursor:
+              type: string
+              description: |-
+                Base64 encoded database query for the next page.
+            prevCursor:
+              type: string
+              description: |-
+                Base64 encoded database query for the previous page.
   securitySchemes:
     JWT:
       type: http
@@ -661,6 +683,33 @@ paths:
               type: array
               items:
                 type: string
+  /entities/by-query:
+    get:
+      operationId: GetEntitiesByQuery
+      responses:
+        '200':
+          description: Ok
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/EntitiesQueryResponse'
+      security:
+        - {}
+        - JWT: []
+      parameters:
+        - in: query
+          name: fields
+          required: false
+          schema:
+            type: string
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: array
+              items:
+                type: string
   /entity-facets:
     get:
       operationId: GetEntityFacets
diff --git a/plugins/catalog-backend/src/service/schema/openapi.ts b/plugins/catalog-backend/src/service/schema/openapi.ts
index 81e585ee01..a759d50c59 100644
--- a/plugins/catalog-backend/src/service/schema/openapi.ts
+++ b/plugins/catalog-backend/src/service/schema/openapi.ts
@@ -352,6 +352,7 @@ export default {
           {
             type: 'object',
             properties: {
+              properties: null,
               links: {
                 type: 'array',
                 items: {
@@ -404,9 +405,10 @@ export default {
                   'A globally unique ID for the entity.\nThis field can not be set by the user at creation time, and the server\nwill reject an attempt to do so. The field will be populated in read\noperations. The field can (optionally) be specified when performing\nupdate or delete operations, but the server is free to reject requests\nthat do so in such a way that it breaks semantics.',
               },
             },
+            description:
+              'Metadata fields common to all versions/kinds of entity.',
           },
         ],
-        description: 'Metadata fields common to all versions/kinds of entity.',
       },
       RecursivePartial_Entity_: {
         type: 'object',
@@ -443,7 +445,7 @@ export default {
           description: {
             type: 'string',
             description:
-              'A text to show to the user to inform about the choices made. Like, it could say\n"Found a CODEOWNERS file that covers this target, so we suggest leaving this\nfield empty; which would currently make it owned by X" where X is taken from the\ncodeowners file.',
+              'A text to show to the user to inform about the choices made. Like, it could say\n"Found a CODEOWNERS file that covers this target, so we suggest leaving this \nfield empty; which would currently make it owned by X" where X is taken from the\ncodeowners file.',
           },
           value: {
             type: 'string',
@@ -549,6 +551,37 @@ export default {
         ],
         description: 'The serialized form of an Error.',
       },
+      EntitiesQueryResponse: {
+        type: 'object',
+        properties: {
+          items: {
+            type: 'array',
+            items: [
+              {
+                $ref: '#/components/schemas/Entity',
+              },
+            ],
+            description: 'The list of entities paginated by a specific filter.',
+          },
+          totalItems: {
+            type: 'number',
+          },
+          pageInfo: {
+            type: 'object',
+            properties: {
+              nextCursor: {
+                type: 'string',
+                description: 'Base64 encoded database query for the next page.',
+              },
+              prevCursor: {
+                type: 'string',
+                description:
+                  'Base64 encoded database query for the previous page.',
+              },
+            },
+          },
+        },
+      },
     },
     securitySchemes: {
       JWT: {
@@ -855,6 +888,52 @@ export default {
         },
       },
     },
+    '/entities/by-query': {
+      get: {
+        operationId: 'GetEntitiesByQuery',
+        responses: {
+          '200': {
+            description: 'Ok',
+            content: {
+              'application/json': {
+                schema: {
+                  $ref: '#/components/schemas/EntitiesQueryResponse',
+                },
+              },
+            },
+          },
+        },
+        security: [
+          {},
+          {
+            JWT: [],
+          },
+        ],
+        parameters: [
+          {
+            in: 'query',
+            name: 'fields',
+            required: false,
+            schema: {
+              type: 'string',
+            },
+          },
+        ],
+        requestBody: {
+          required: true,
+          content: {
+            'application/json': {
+              schema: {
+                type: 'array',
+                items: {
+                  type: 'string',
+                },
+              },
+            },
+          },
+        },
+      },
+    },
     '/entity-facets': {
       get: {
         operationId: 'GetEntityFacets',
diff --git a/plugins/openapi-router-common/package.json b/plugins/openapi-router-common/package.json
index 06a4c4e8ee..3c0857a5c7 100644
--- a/plugins/openapi-router-common/package.json
+++ b/plugins/openapi-router-common/package.json
@@ -30,7 +30,7 @@
     "dist"
   ],
   "dependencies": {
-    "express": "^4.18.2",
+    "express": "^4.17.1",
     "json-schema-to-ts": "^2.6.2",
     "openapi-types": "^12.1.0",
     "openapi3-ts": "^3.1.2",
diff --git a/plugins/openapi-router-common/src/example.ts b/plugins/openapi-router-common/src/example.ts
new file mode 100644
index 0000000000..d2dba3298a
--- /dev/null
+++ b/plugins/openapi-router-common/src/example.ts
@@ -0,0 +1,41 @@
+/*
+ * Copyright 2023 The Backstage Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import express, { Router } from 'express';
+import { ApiRouter, DeepWriteable } from './router';
+import doc from './schema/petstore';
+
+interface RouterOptions {}
+
+export async function createRouter(
+  options: RouterOptions,
+): Promise<express.Router> {
+  console.log(options);
+  const router = Router() as ApiRouter<DeepWriteable<typeof doc>>;
+
+  router.get('/pets/:uid', (req, res) => {
+    res.json({
+      id: 1,
+      name: req.params.uid,
+    });
+  });
+
+  // router.get('/pet') will complain with a TS error
+
+  router.post('/pets', (_, res) => {
+    res.send();
+  });
+  return router;
+}
diff --git a/plugins/openapi-router-common/src/router.ts b/plugins/openapi-router-common/src/router.ts
index 62e116727b..16b627e62e 100644
--- a/plugins/openapi-router-common/src/router.ts
+++ b/plugins/openapi-router-common/src/router.ts
@@ -13,356 +13,27 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-import { ErrorRequestHandler, RequestHandler, Router } from 'express';
-import core, { ParamsDictionary } from 'express-serve-static-core';
-import { FromSchema, JSONSchema7 } from 'json-schema-to-ts';
-import {
-  DocPathMethod,
-  DocPathTemplate,
-  MethodAwareDocPath,
-  PathTemplate,
-  RequestBodySchema,
-  RequiredDoc,
-  ValueOf,
-} from './types';
-import { ResponseSchemas } from './types/response';
+import { Router } from 'express';
+import { RequiredDoc } from './types';
+import { DocRequestMatcher } from './types/express';
 
 export type DeepWriteable<T> = {
   -readonly [P in keyof T]: DeepWriteable<T[P]>;
 };
-
-const doc = {
-  openapi: '3.1.0',
-  info: {
-    version: '1.0.0',
-    title: 'Swagger Petstore',
-    license: {
-      name: 'MIT',
-      url: 'https://opensource.org/licenses/MIT',
-    },
-  },
-  servers: [
-    {
-      url: 'http://petstore.swagger.io/v1',
-    },
-  ],
-  paths: {
-    '/pets': {
-      get: {
-        summary: 'List all pets',
-        operationId: 'listPets',
-        tags: ['pets'],
-        parameters: [
-          {
-            name: 'limit',
-            in: 'query',
-            description: 'How many items to return at one time (max 100)',
-            required: false,
-            schema: {
-              type: 'integer',
-              format: 'int32',
-            },
-          },
-        ],
-        responses: {
-          '200': {
-            description: 'A paged array of pets',
-            headers: {
-              'x-next': {
-                description: 'A link to the next page of responses',
-                schema: {
-                  type: 'string',
-                },
-              },
-            },
-            content: {
-              'application/json': {
-                schema: {
-                  $ref: '#/components/schemas/Pets',
-                },
-              },
-            },
-          },
-          default: {
-            description: 'unexpected error',
-            content: {
-              'application/json': {
-                schema: {
-                  $ref: '#/components/schemas/Error',
-                },
-              },
-            },
-          },
-        },
-      },
-      post: {
-        summary: 'Create a pet',
-        operationId: 'createPets',
-        tags: ['pets'],
-        responses: {
-          '201': {
-            description: 'Null response',
-          },
-          default: {
-            description: 'unexpected error',
-            content: {
-              'application/json': {
-                schema: {
-                  $ref: '#/components/schemas/Error',
-                },
-              },
-            },
-          },
-        },
-      },
-    },
-    '/pets/{petId}': {
-      get: {
-        summary: 'Info for a specific pet',
-        operationId: 'showPetById',
-        tags: ['pets'],
-        parameters: [
-          {
-            name: 'petId',
-            in: 'path',
-            required: true,
-            description: 'The id of the pet to retrieve',
-            schema: {
-              type: 'string',
-            },
-          },
-        ],
-        responses: {
-          '200': {
-            description: 'Expected response to a valid request',
-            content: {
-              'application/json': {
-                schema: {
-                  $ref: '#/components/schemas/Pet',
-                },
-              },
-            },
-          },
-          default: {
-            description: 'unexpected error',
-            content: {
-              'application/json': {
-                schema: {
-                  $ref: '#/components/schemas/Error',
-                },
-              },
-            },
-          },
-        },
-      },
-    },
-  },
-  components: {
-    schemas: {
-      Pet: {
-        type: 'object',
-        required: ['id', 'name'],
-        properties: {
-          id: {
-            type: 'integer',
-            format: 'int64',
-          },
-          name: {
-            type: 'string',
-          },
-          tag: {
-            type: 'string',
-          },
-        },
-      },
-      Pets: {
-        type: 'array',
-        items: {
-          $ref: '#/components/schemas/Pet',
-        },
-      },
-      Error: {
-        type: 'object',
-        required: ['code', 'message'],
-        properties: {
-          code: {
-            type: 'integer',
-            format: 'int32',
-          },
-          message: {
-            type: 'string',
-          },
-        },
-      },
-    },
-  },
-} as const;
-
-type RemoveTail<
-  S extends string,
-  Tail extends string,
-> = S extends `${infer P}${Tail}` ? P : S;
-type GetRouteParameter<S extends string> = RemoveTail<
-  RemoveTail<RemoveTail<S, `/${string}`>, `-${string}`>,
-  `.${string}`
->;
-export type RouteParameters<Route extends string> = string extends Route
-  ? ParamsDictionary
-  : Route extends `${string}(${string}`
-  ? ParamsDictionary
-  : Route extends `${string}:${infer Rest}`
-  ? (GetRouteParameter<Rest> extends never
-      ? ParamsDictionary
-      : GetRouteParameter<Rest> extends `${infer ParamName}?`
-      ? { [P in ParamName]?: string }
-      : { [P in GetRouteParameter<Rest>]: string }) &
-      (Rest extends `${GetRouteParameter<Rest>}${infer Next}`
-        ? RouteParameters<Next>
-        : unknown)
-  : {};
-interface ParsedQs {
-  [key: string]: undefined | string | string[] | ParsedQs | ParsedQs[];
-}
-
-// oh boy don't do this
-type UnionToIntersection<U> = (U extends any ? (k: U) => void : never) extends (
-  k: infer I,
-) => void
-  ? I
-  : never;
-type LastOf<T> = UnionToIntersection<
-  T extends any ? () => T : never
-> extends () => infer R
-  ? R
-  : never;
-
-// TS4.0+
-type Push<T extends any[], V> = [...T, V];
-
-// TS4.1+
-type TuplifyUnion<
-  T,
-  L = LastOf<T>,
-  N = [T] extends [never] ? true : false,
-> = true extends N ? [] : Push<TuplifyUnion<Exclude<T, L>>, L>;
-
-type ConvertAll<T, R extends ReadonlyArray<unknown> = []> = T extends [
-  infer First extends JSONSchema7,
-  ...infer Rest,
-]
-  ? ConvertAll<Rest, [...R, FromSchema<First>]>
-  : R;
-
-type ResponseBodyToJsonSchema<
-  Doc extends RequiredDoc,
-  Path extends PathTemplate<Extract<keyof Doc['paths'], string>>,
-  Method extends DocPathMethod<Doc, Path>,
-> = ConvertAll<
-  TuplifyUnion<ValueOf<ResponseSchemas<Doc, Path, Method>>>
->[number];
-
-type RequestBodyToJsonSchema<
-  Doc extends RequiredDoc,
-  Path extends PathTemplate<Extract<keyof Doc['paths'], string>>,
-  Method extends DocPathMethod<Doc, Path>,
-> = ConvertAll<
-  TuplifyUnion<ValueOf<RequestBodySchema<Doc, Path, Method>>>
->[number];
-export type RequestHandlerParams<
-  P,
-  ResBody,
-  ReqBody,
-  ReqQuery,
-  LocalsObj extends Record<string, any>,
-> =
-  | RequestHandler<P, ResBody, ReqBody, ReqQuery, LocalsObj>
-  | ErrorRequestHandler<P, ResBody, ReqBody, ReqQuery, LocalsObj>;
-
-type DocRequestHandler<
-  Doc extends RequiredDoc,
-  Path extends DocPathTemplate<Doc>,
-  Method extends keyof Doc['paths'][Path],
-> = core.RequestHandler<
-  core.ParamsDictionary,
-  // From https://stackoverflow.com/questions/71393738/typescript-intersection-not-union-type-from-json-schema.
-  ResponseBodyToJsonSchema<Doc, Path, Method>,
-  RequestBodyToJsonSchema<Doc, Path, Method>,
-  ParsedQs,
-  Record<string, string>
->;
-
-export interface ApiRouterMatcher<
-  Doc extends RequiredDoc,
-  Path extends DocPathTemplate<Doc>,
-  Method extends DocPathMethod<Doc, Path>,
-  T,
-> {
-  (
-    path: MethodAwareDocPath<Doc, Path, Method>,
-    ...handlers: Array<DocRequestHandler<Doc, Path, Method>>
-  ): T;
-}
-
 export interface ApiRouter<Doc extends RequiredDoc> extends Router {
-  get<Path extends MethodAwareDocPath<Doc, DocPathTemplate<Doc>, 'get'>>(
-    path: Path,
-    ...handlers: DocRequestHandler<Doc, Path, 'get'>[]
-  ): this;
+  get: DocRequestMatcher<Doc, this, 'get'>;
 
-  post<Path extends MethodAwareDocPath<Doc, DocPathTemplate<Doc>, 'post'>>(
-    path: Path,
-    ...handlers: DocRequestHandler<Doc, Path, 'post'>[]
-  ): this;
+  post: DocRequestMatcher<Doc, this, 'get'>;
 
-  all<Path extends MethodAwareDocPath<Doc, DocPathTemplate<Doc>, 'all'>>(
-    path: Path,
-    ...handlers: DocRequestHandler<Doc, Path, 'all'>[]
-  ): this;
+  all: DocRequestMatcher<Doc, this, 'get'>;
 
-  put<Path extends MethodAwareDocPath<Doc, DocPathTemplate<Doc>, 'put'>>(
-    path: Path,
-    ...handlers: DocRequestHandler<Doc, Path, 'put'>[]
-  ): this;
-  delete<Path extends MethodAwareDocPath<Doc, DocPathTemplate<Doc>, 'delete'>>(
-    path: Path,
-    ...handlers: DocRequestHandler<Doc, Path, 'delete'>[]
-  ): this;
-  patch<Path extends MethodAwareDocPath<Doc, DocPathTemplate<Doc>, 'patch'>>(
-    path: Path,
-    ...handlers: DocRequestHandler<Doc, Path, 'patch'>[]
-  ): this;
-  options<
-    Path extends MethodAwareDocPath<Doc, DocPathTemplate<Doc>, 'options'>,
-  >(
-    path: Path,
-    ...handlers: DocRequestHandler<Doc, Path, 'options'>[]
-  ): this;
-  head<Path extends MethodAwareDocPath<Doc, DocPathTemplate<Doc>, 'head'>>(
-    path: Path,
-    ...handlers: DocRequestHandler<Doc, Path, 'head'>[]
-  ): this;
-}
-
-interface RouterOptions {}
-
-export async function createRouter(options: RouterOptions) {
-  console.log(options);
-  const router = Router() as ApiRouter<DeepWriteable<typeof doc>>;
-
-  router.get('/pets/:uid', (req, res) => {
-    res.json({
-      id: 1,
-      name: req.params.uid,
-    });
-  });
-
-  // router.get('/pet') will complain with a TS error
-
-  router.post('/pets', (req, res) => {
-    res.send({
-      message: req.path,
-      code: 1,
-    });
-  });
-  return router;
+  put: DocRequestMatcher<Doc, this, 'get'>;
+
+  delete: DocRequestMatcher<Doc, this, 'get'>;
+
+  patch: DocRequestMatcher<Doc, this, 'get'>;
+
+  options: DocRequestMatcher<Doc, this, 'get'>;
+
+  head: DocRequestMatcher<Doc, this, 'get'>;
 }
diff --git a/plugins/openapi-router-common/src/schema/petstore.ts b/plugins/openapi-router-common/src/schema/petstore.ts
new file mode 100644
index 0000000000..308e3925e0
--- /dev/null
+++ b/plugins/openapi-router-common/src/schema/petstore.ts
@@ -0,0 +1,181 @@
+/*
+ * Copyright 2023 The Backstage Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+export default {
+  openapi: '3.1.0',
+  info: {
+    version: '1.0.0',
+    title: 'Swagger Petstore',
+    license: {
+      name: 'MIT',
+      url: 'https://opensource.org/licenses/MIT',
+    },
+  },
+  servers: [
+    {
+      url: 'http://petstore.swagger.io/v1',
+    },
+  ],
+  paths: {
+    '/pets': {
+      get: {
+        summary: 'List all pets',
+        operationId: 'listPets',
+        tags: ['pets'],
+        parameters: [
+          {
+            name: 'limit',
+            in: 'query',
+            description: 'How many items to return at one time (max 100)',
+            required: false,
+            schema: {
+              type: 'integer',
+              format: 'int32',
+            },
+          },
+        ],
+        responses: {
+          '200': {
+            description: 'A paged array of pets',
+            headers: {
+              'x-next': {
+                description: 'A link to the next page of responses',
+                schema: {
+                  type: 'string',
+                },
+              },
+            },
+            content: {
+              'application/json': {
+                schema: {
+                  $ref: '#/components/schemas/Pets',
+                },
+              },
+            },
+          },
+          default: {
+            description: 'unexpected error',
+            content: {
+              'application/json': {
+                schema: {
+                  $ref: '#/components/schemas/Error',
+                },
+              },
+            },
+          },
+        },
+      },
+      post: {
+        summary: 'Create a pet',
+        operationId: 'createPets',
+        tags: ['pets'],
+        responses: {
+          '201': {
+            description: 'Null response',
+          },
+          default: {
+            description: 'unexpected error',
+            content: {
+              'application/json': {
+                schema: {
+                  $ref: '#/components/schemas/Error',
+                },
+              },
+            },
+          },
+        },
+      },
+    },
+    '/pets/{petId}': {
+      get: {
+        summary: 'Info for a specific pet',
+        operationId: 'showPetById',
+        tags: ['pets'],
+        parameters: [
+          {
+            name: 'petId',
+            in: 'path',
+            required: true,
+            description: 'The id of the pet to retrieve',
+            schema: {
+              type: 'string',
+            },
+          },
+        ],
+        responses: {
+          '200': {
+            description: 'Expected response to a valid request',
+            content: {
+              'application/json': {
+                schema: {
+                  $ref: '#/components/schemas/Pet',
+                },
+              },
+            },
+          },
+          default: {
+            description: 'unexpected error',
+            content: {
+              'application/json': {
+                schema: {
+                  $ref: '#/components/schemas/Error',
+                },
+              },
+            },
+          },
+        },
+      },
+    },
+  },
+  components: {
+    schemas: {
+      Pet: {
+        type: 'object',
+        required: ['id', 'name'],
+        properties: {
+          id: {
+            type: 'integer',
+            format: 'int64',
+          },
+          name: {
+            type: 'string',
+          },
+          tag: {
+            type: 'string',
+          },
+        },
+      },
+      Pets: {
+        type: 'array',
+        items: {
+          $ref: '#/components/schemas/Pet',
+        },
+      },
+      Error: {
+        type: 'object',
+        required: ['code', 'message'],
+        properties: {
+          code: {
+            type: 'integer',
+            format: 'int32',
+          },
+          message: {
+            type: 'string',
+          },
+        },
+      },
+    },
+  },
+} as const;
diff --git a/plugins/openapi-router-common/src/standaloneServer.ts b/plugins/openapi-router-common/src/standaloneServer.ts
index aef8f006ff..f7c2ec2c61 100644
--- a/plugins/openapi-router-common/src/standaloneServer.ts
+++ b/plugins/openapi-router-common/src/standaloneServer.ts
@@ -17,7 +17,7 @@
 import { Server } from 'http';
 import { Logger } from 'winston';
 import { createServiceBuilder } from '@backstage/backend-common';
-import { createRouter } from './router';
+import { createRouter } from './example';
 
 export interface ServerOptions {
   port: number;
diff --git a/plugins/openapi-router-common/src/types/common.ts b/plugins/openapi-router-common/src/types/common.ts
index f514c88d13..834f1b49f5 100644
--- a/plugins/openapi-router-common/src/types/common.ts
+++ b/plugins/openapi-router-common/src/types/common.ts
@@ -18,6 +18,7 @@
  * Pulled from https://github.com/varanauskas/oatx.
  */
 
+import { FromSchema, JSONSchema7 } from 'json-schema-to-ts';
 import type {
   ContentObject,
   OpenAPIObject,
@@ -25,7 +26,8 @@ import type {
 } from 'openapi3-ts';
 
 export type RequiredDoc = Pick<OpenAPIObject, 'paths' | 'components'>;
-export type PathDoc = { paths: Record<string, unknown> };
+
+export type PathDoc = Pick<OpenAPIObject, 'paths'>;
 
 /**
  * Get value types of `T`
@@ -129,4 +131,36 @@ export type ObjectWithContentSchema<
   Object extends { content?: ContentObject },
 > = Object['content'] extends ContentObject
   ? SchemaRef<Doc, Object['content']['application/json']['schema']>
+  : unknown;
+
+/**
+ * From https://stackoverflow.com/questions/71393738/typescript-intersection-not-union-type-from-json-schema.
+ *
+ * StackOverflow says not to do this, but union types aren't possible any other way.
+ */
+
+type UnionToIntersection<U> = (U extends any ? (k: U) => void : never) extends (
+  k: infer I,
+) => void
+  ? I
   : never;
+type LastOf<T> = UnionToIntersection<
+  T extends any ? () => T : never
+> extends () => infer R
+  ? R
+  : never;
+
+type Push<T extends any[], V> = [...T, V];
+
+export type TuplifyUnion<
+  T,
+  L = LastOf<T>,
+  N = [T] extends [never] ? true : false,
+> = true extends N ? [] : Push<TuplifyUnion<Exclude<T, L>>, L>;
+
+export type ConvertAll<T, R extends ReadonlyArray<unknown> = []> = T extends [
+  infer First extends JSONSchema7,
+  ...infer Rest,
+]
+  ? ConvertAll<Rest, [...R, FromSchema<First>]>
+  : R;
diff --git a/plugins/openapi-router-common/src/types/express.ts b/plugins/openapi-router-common/src/types/express.ts
new file mode 100644
index 0000000000..055235af99
--- /dev/null
+++ b/plugins/openapi-router-common/src/types/express.ts
@@ -0,0 +1,86 @@
+/*
+ * Copyright 2023 The Backstage Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { Application } from 'express';
+import core from 'express-serve-static-core';
+import { DocPathTemplate, MethodAwareDocPath, RequiredDoc } from './common';
+import { RequestBodyToJsonSchema } from './requests';
+import { ResponseBodyToJsonSchema } from './response';
+
+interface ParsedQs {
+  [key: string]: undefined | string | string[] | ParsedQs | ParsedQs[];
+}
+
+export type DocRequestHandler<
+  Doc extends RequiredDoc,
+  Path extends DocPathTemplate<Doc>,
+  Method extends keyof Doc['paths'][Path],
+> = core.RequestHandler<
+  core.ParamsDictionary,
+  ResponseBodyToJsonSchema<Doc, Path, Method>,
+  RequestBodyToJsonSchema<Doc, Path, Method>,
+  ParsedQs,
+  Record<string, string>
+>;
+
+export type DocRequestHandlerParams<
+  Doc extends RequiredDoc,
+  Path extends DocPathTemplate<Doc>,
+  Method extends keyof Doc['paths'][Path],
+> = core.RequestHandlerParams<
+  core.ParamsDictionary,
+  ResponseBodyToJsonSchema<Doc, Path, Method>,
+  RequestBodyToJsonSchema<Doc, Path, Method>,
+  ParsedQs,
+  Record<string, string>
+>;
+
+export type PathParams = string | RegExp | Array<string | RegExp>;
+
+export interface DocRequestMatcher<
+  Doc extends RequiredDoc,
+  T,
+  Method extends
+    | 'all'
+    | 'get'
+    | 'post'
+    | 'put'
+    | 'delete'
+    | 'patch'
+    | 'options'
+    | 'head' = any,
+> {
+  <Path extends MethodAwareDocPath<Doc, DocPathTemplate<Doc>, Method>>(
+    path: Path,
+    ...handlers: DocRequestHandler<Doc, Path, Method>[]
+  ): T;
+  <Path extends MethodAwareDocPath<Doc, DocPathTemplate<Doc>, Method>>(
+    path: Path,
+    ...handlers: Array<DocRequestHandler<Doc, Path, Method>>
+  ): T;
+  <Path extends MethodAwareDocPath<Doc, DocPathTemplate<Doc>, Method>>(
+    path: Path,
+    ...handlers: Array<DocRequestHandlerParams<Doc, Path, Method>>
+  ): T;
+  <Path extends MethodAwareDocPath<Doc, DocPathTemplate<Doc>, Method>>(
+    path: PathParams,
+    ...handlers: Array<DocRequestHandler<Doc, Path, Method>>
+  ): T;
+  <Path extends MethodAwareDocPath<Doc, DocPathTemplate<Doc>, Method>>(
+    path: PathParams,
+    ...handlers: Array<DocRequestHandlerParams<Doc, Path, Method>>
+  ): T;
+  (path: PathParams, subApplication: Application): T;
+}
diff --git a/plugins/openapi-router-common/src/types/requests.ts b/plugins/openapi-router-common/src/types/requests.ts
index 832cf34956..ae05a27537 100644
--- a/plugins/openapi-router-common/src/types/requests.ts
+++ b/plugins/openapi-router-common/src/types/requests.ts
@@ -28,6 +28,10 @@ import type {
   DocPath,
   DocPathMethod,
   DocPathTemplate,
+  PathTemplate,
+  ConvertAll,
+  TuplifyUnion,
+  ValueOf,
 } from './common';
 
 type RequestBody<
@@ -50,4 +54,12 @@ export type RequestBodySchema<
   Method extends DocPathMethod<Doc, Path>,
 > = RequestBody<Doc, DocPath<Doc, Path>, Method> extends RequestBodyObject
   ? ObjectWithContentSchema<Doc, RequestBody<Doc, DocPath<Doc, Path>, Method>>
-  : never;
+  : unknown;
+
+export type RequestBodyToJsonSchema<
+  Doc extends RequiredDoc,
+  Path extends PathTemplate<Extract<keyof Doc['paths'], string>>,
+  Method extends DocPathMethod<Doc, Path>,
+> = ConvertAll<
+  TuplifyUnion<ValueOf<RequestBodySchema<Doc, Path, Method>>>
+>[number];
diff --git a/plugins/openapi-router-common/src/types/response.ts b/plugins/openapi-router-common/src/types/response.ts
index 93ec8a61fa..5c01a70673 100644
--- a/plugins/openapi-router-common/src/types/response.ts
+++ b/plugins/openapi-router-common/src/types/response.ts
@@ -28,6 +28,10 @@ import type {
   DocPath,
   DocPathMethod,
   DocPathTemplate,
+  PathTemplate,
+  ConvertAll,
+  ValueOf,
+  TuplifyUnion,
 } from './common';
 
 type Response<
@@ -81,5 +85,13 @@ export type ResponseSchemas<
         Doc,
         Responses<Doc, DocPath<Doc, Path>, Method>[StatusCode]
       >
-    : never;
+    : unknown;
 };
+
+export type ResponseBodyToJsonSchema<
+  Doc extends RequiredDoc,
+  Path extends PathTemplate<Extract<keyof Doc['paths'], string>>,
+  Method extends DocPathMethod<Doc, Path>,
+> = ConvertAll<
+  TuplifyUnion<ValueOf<ResponseSchemas<Doc, Path, Method>>>
+>[number];
diff --git a/yarn.lock b/yarn.lock
index fd223f444f..a3a011d2ca 100644
--- a/yarn.lock
+++ b/yarn.lock
@@ -7809,7 +7809,7 @@ __metadata:
   resolution: "@backstage/plugin-openapi-router@workspace:plugins/openapi-router-common"
   dependencies:
     "@backstage/cli": "workspace:^"
-    express: ^4.18.2
+    express: ^4.17.1
     json-schema-to-ts: ^2.6.2
     openapi-types: ^12.1.0
     openapi3-ts: ^3.1.2
@@ -24164,7 +24164,7 @@ __metadata:
   languageName: node
   linkType: hard
 
-"express@npm:^4.17.1, express@npm:^4.17.3, express@npm:^4.18.1, express@npm:^4.18.2":
+"express@npm:^4.17.1, express@npm:^4.17.3, express@npm:^4.18.1":
   version: 4.18.2
   resolution: "express@npm:4.18.2"
   dependencies:

From 4669b87364d85f43955211a4d1cec9852221ce51 Mon Sep 17 00:00:00 2001
From: Aramis Sennyey <sennyeya@amazon.com>
Date: Wed, 22 Feb 2023 17:00:48 -0500
Subject: [PATCH 11/61] Fix API definitions and update types.

Signed-off-by: Aramis Sennyey <sennyeya@amazon.com>
---
 plugins/catalog-backend/openapi.yaml          |   46 +-
 .../src/service/schema/openapi.ts             |   61 +-
 plugins/openapi-router-common/src/example.ts  |   14 +-
 plugins/openapi-router-common/src/router.ts   |   14 +-
 .../src/schema/openapi.ts                     | 1263 +++++++++++++++++
 .../src/schema/petstore.ts                    |    2 +
 .../openapi-router-common/src/types/common.ts |    6 +-
 .../src/types/express.ts                      |   16 +-
 .../src/types/requests.ts                     |   10 +-
 .../src/types/response.ts                     |    9 +-
 10 files changed, 1367 insertions(+), 74 deletions(-)
 create mode 100644 plugins/openapi-router-common/src/schema/openapi.ts

diff --git a/plugins/catalog-backend/openapi.yaml b/plugins/catalog-backend/openapi.yaml
index 5feacb8599..c53a6443ba 100644
--- a/plugins/catalog-backend/openapi.yaml
+++ b/plugins/catalog-backend/openapi.yaml
@@ -6,6 +6,7 @@ info:
   description: The Backstage backend plugin that provides the Backstage catalog
   license:
     name: Apache-2.0
+    url: http://www.apache.org/licenses/LICENSE-2.0.html
   contact: {}
 
 servers:
@@ -18,17 +19,6 @@ components:
   requestBodies: {}
   responses: {}
   schemas:
-    RefreshOptions:
-      type: object
-      properties:
-        authorizationToken:
-          type: string
-        entityRef:
-          type: string
-          description: The reference to a single entity that should be refreshed
-      required:
-        - entityRef
-      description: Options for requesting a refresh of entities in the catalog.
     JsonObject:
       type: object
       properties: {}
@@ -57,6 +47,7 @@ components:
       required:
         - url
       description: A link to external information that is related to the entity.
+      additionalProperties: false
     EntityMeta:
       allOf:
         - $ref: '#/components/schemas/JsonObject'
@@ -133,6 +124,7 @@ components:
           required:
             - name
       description: Metadata fields common to all versions/kinds of entity.
+      additionalProperties: false
     EntityRelation:
       type: object
       properties:
@@ -146,6 +138,7 @@ components:
         - targetRef
         - type
       description: A relation of a specific type to another entity in the catalog.
+      additionalProperties: false
     Entity:
       type: object
       properties:
@@ -171,6 +164,7 @@ components:
         - kind
         - apiVersion
       description: The parts of the format that's common to all versions/kinds of entity.
+      additionalProperties: false
     EntityAncestryResponse:
       type: object
       properties:
@@ -193,6 +187,7 @@ components:
       required:
         - items
         - rootEntityRef
+      additionalProperties: false
     EntitiesBatchResponse:
       type: object
       properties:
@@ -207,6 +202,7 @@ components:
             that are null signify that no entity existed with that ref.
       required:
         - items
+      additionalProperties: false
     EntityFacet:
       type: object
       properties:
@@ -214,6 +210,7 @@ components:
           type: string
         count:
           type: number
+      additionalProperties: false
     EntityFacets:
       type: array
       items:
@@ -227,6 +224,7 @@ components:
             $ref: '#/components/schemas/EntityFacets'
       required:
         - facets
+      additionalProperties: false
     Location:
       type: object
       properties:
@@ -241,6 +239,7 @@ components:
         - type
         - id
       description: Entity location for a specific entity.
+      additionalProperties: false
     LocationSpec:
       type: object
       properties:
@@ -257,6 +256,7 @@ components:
         - target
         - type
       description: Holds the entity location information.
+      additionalProperties: false
     AnalyzeLocationExistingEntity:
       type: object
       properties:
@@ -275,6 +275,7 @@ components:
         read and emitted like this so that the frontend can inform the user that it
         located them and can make sure to register them as well if they weren't
         already
+      additionalProperties: false
     RecursivePartialEntityRelation:
       type: object
       properties:
@@ -285,6 +286,7 @@ components:
           type: string
           description: The type of the relation.
       description: A relation of a specific type to another entity in the catalog.
+      additionalProperties: false
     RecursivePartialEntityMeta:
       allOf:
         - $ref: '#/components/schemas/JsonObject'
@@ -360,6 +362,7 @@ components:
                 update or delete operations, but the server is free to reject requests
                 that do so in such a way that it breaks semantics.
           description: Metadata fields common to all versions/kinds of entity.
+      additionalProperties: false
     RecursivePartial_Entity_:
       type: object
       properties:
@@ -381,6 +384,7 @@ components:
             $ref: '#/components/schemas/RecursivePartialEntityRelation'
           description: The relations that this entity has with other entities.
       description: Makes all keys of an entire hierarchy optional.
+      additionalProperties: false
     AnalyzeLocationEntityField:
       type: object
       properties:
@@ -411,6 +415,7 @@ components:
         - value
         - state
         - field
+      additionalProperties: false
     AnalyzeLocationGenerateEntity:
       type: object
       properties:
@@ -429,6 +434,7 @@ components:
         the frontend. It'll probably contain a (possibly incomplete) entity, plus
         enough info for the frontend to know what form data to show to the user
         for overriding/completing the info.
+      additionalProperties: false
     AnalyzeLocationResponse:
       type: object
       properties:
@@ -443,6 +449,7 @@ components:
       required:
         - generateEntities
         - existingEntityFiles
+      additionalProperties: false
     LocationInput:
       type: object
       properties:
@@ -459,6 +466,7 @@ components:
         - type
         - target
         - presence
+      additionalProperties: false
     SerializedError:
       allOf:
         - $ref: '#/components/schemas/JsonObject'
@@ -480,13 +488,14 @@ components:
             - message
             - name
       description: The serialized form of an Error.
+      additionalProperties: false
     EntitiesQueryResponse:
       type: object
       properties:
         items:
           type: array
           items:
-            - $ref: '#/components/schemas/Entity'
+            $ref: '#/components/schemas/Entity'
           description: |-
             The list of entities paginated by a specific filter.
         totalItems:
@@ -502,6 +511,7 @@ components:
               type: string
               description: |-
                 Base64 encoded database query for the previous page.
+      additionalProperties: false
   securitySchemes:
     JWT:
       type: http
@@ -523,7 +533,17 @@ paths:
         content:
           application/json:
             schema:
-              $ref: '#/components/schemas/RefreshOptions'
+              type: object
+              properties:
+                authorizationToken:
+                  type: string
+                entityRef:
+                  type: string
+                  description: The reference to a single entity that should be refreshed
+              required:
+                - entityRef
+              description: Options for requesting a refresh of entities in the catalog.
+              additionalProperties: false
   /entities:
     get:
       operationId: GetEntities
diff --git a/plugins/catalog-backend/src/service/schema/openapi.ts b/plugins/catalog-backend/src/service/schema/openapi.ts
index a759d50c59..8d011ad7a4 100644
--- a/plugins/catalog-backend/src/service/schema/openapi.ts
+++ b/plugins/catalog-backend/src/service/schema/openapi.ts
@@ -22,6 +22,7 @@ export default {
       'The Backstage backend plugin that provides the Backstage catalog',
     license: {
       name: 'Apache-2.0',
+      url: 'http://www.apache.org/licenses/LICENSE-2.0.html',
     },
     contact: {},
   },
@@ -37,22 +38,6 @@ export default {
     requestBodies: {},
     responses: {},
     schemas: {
-      RefreshOptions: {
-        type: 'object',
-        properties: {
-          authorizationToken: {
-            type: 'string',
-          },
-          entityRef: {
-            type: 'string',
-            description:
-              'The reference to a single entity that should be refreshed',
-          },
-        },
-        required: ['entityRef'],
-        description:
-          'Options for requesting a refresh of entities in the catalog.',
-      },
       JsonObject: {
         type: 'object',
         properties: {},
@@ -91,6 +76,7 @@ export default {
         required: ['url'],
         description:
           'A link to external information that is related to the entity.',
+        additionalProperties: false,
       },
       EntityMeta: {
         allOf: [
@@ -156,6 +142,7 @@ export default {
           },
         ],
         description: 'Metadata fields common to all versions/kinds of entity.',
+        additionalProperties: false,
       },
       EntityRelation: {
         type: 'object',
@@ -172,6 +159,7 @@ export default {
         required: ['targetRef', 'type'],
         description:
           'A relation of a specific type to another entity in the catalog.',
+        additionalProperties: false,
       },
       Entity: {
         type: 'object',
@@ -203,6 +191,7 @@ export default {
         required: ['metadata', 'kind', 'apiVersion'],
         description:
           "The parts of the format that's common to all versions/kinds of entity.",
+        additionalProperties: false,
       },
       EntityAncestryResponse: {
         type: 'object',
@@ -230,6 +219,7 @@ export default {
           },
         },
         required: ['items', 'rootEntityRef'],
+        additionalProperties: false,
       },
       EntitiesBatchResponse: {
         type: 'object',
@@ -249,6 +239,7 @@ export default {
           },
         },
         required: ['items'],
+        additionalProperties: false,
       },
       EntityFacet: {
         type: 'object',
@@ -260,6 +251,7 @@ export default {
             type: 'number',
           },
         },
+        additionalProperties: false,
       },
       EntityFacets: {
         type: 'array',
@@ -278,6 +270,7 @@ export default {
           },
         },
         required: ['facets'],
+        additionalProperties: false,
       },
       Location: {
         type: 'object',
@@ -294,6 +287,7 @@ export default {
         },
         required: ['target', 'type', 'id'],
         description: 'Entity location for a specific entity.',
+        additionalProperties: false,
       },
       LocationSpec: {
         type: 'object',
@@ -311,6 +305,7 @@ export default {
         },
         required: ['target', 'type'],
         description: 'Holds the entity location information.',
+        additionalProperties: false,
       },
       AnalyzeLocationExistingEntity: {
         type: 'object',
@@ -328,6 +323,7 @@ export default {
         required: ['entity', 'isRegistered', 'location'],
         description:
           "If the folder pointed to already contained catalog info yaml files, they are\nread and emitted like this so that the frontend can inform the user that it\nlocated them and can make sure to register them as well if they weren't\nalready",
+        additionalProperties: false,
       },
       RecursivePartialEntityRelation: {
         type: 'object',
@@ -343,6 +339,7 @@ export default {
         },
         description:
           'A relation of a specific type to another entity in the catalog.',
+        additionalProperties: false,
       },
       RecursivePartialEntityMeta: {
         allOf: [
@@ -409,6 +406,7 @@ export default {
               'Metadata fields common to all versions/kinds of entity.',
           },
         ],
+        additionalProperties: false,
       },
       RecursivePartial_Entity_: {
         type: 'object',
@@ -438,6 +436,7 @@ export default {
           },
         },
         description: 'Makes all keys of an entire hierarchy optional.',
+        additionalProperties: false,
       },
       AnalyzeLocationEntityField: {
         type: 'object',
@@ -468,6 +467,7 @@ export default {
           },
         },
         required: ['description', 'value', 'state', 'field'],
+        additionalProperties: false,
       },
       AnalyzeLocationGenerateEntity: {
         type: 'object',
@@ -485,6 +485,7 @@ export default {
         required: ['fields', 'entity'],
         description:
           "This is some form of representation of what the analyzer could deduce.\nWe should probably have a chat about how this can best be conveyed to\nthe frontend. It'll probably contain a (possibly incomplete) entity, plus\nenough info for the frontend to know what form data to show to the user\nfor overriding/completing the info.",
+        additionalProperties: false,
       },
       AnalyzeLocationResponse: {
         type: 'object',
@@ -503,6 +504,7 @@ export default {
           },
         },
         required: ['generateEntities', 'existingEntityFiles'],
+        additionalProperties: false,
       },
       LocationInput: {
         type: 'object',
@@ -519,6 +521,7 @@ export default {
           },
         },
         required: ['type', 'target', 'presence'],
+        additionalProperties: false,
       },
       SerializedError: {
         allOf: [
@@ -550,17 +553,16 @@ export default {
           },
         ],
         description: 'The serialized form of an Error.',
+        additionalProperties: false,
       },
       EntitiesQueryResponse: {
         type: 'object',
         properties: {
           items: {
             type: 'array',
-            items: [
-              {
-                $ref: '#/components/schemas/Entity',
-              },
-            ],
+            items: {
+              $ref: '#/components/schemas/Entity',
+            },
             description: 'The list of entities paginated by a specific filter.',
           },
           totalItems: {
@@ -581,6 +583,7 @@ export default {
             },
           },
         },
+        additionalProperties: false,
       },
     },
     securitySchemes: {
@@ -612,7 +615,21 @@ export default {
           content: {
             'application/json': {
               schema: {
-                $ref: '#/components/schemas/RefreshOptions',
+                type: 'object',
+                properties: {
+                  authorizationToken: {
+                    type: 'string',
+                  },
+                  entityRef: {
+                    type: 'string',
+                    description:
+                      'The reference to a single entity that should be refreshed',
+                  },
+                },
+                required: ['entityRef'],
+                description:
+                  'Options for requesting a refresh of entities in the catalog.',
+                additionalProperties: false,
               },
             },
           },
diff --git a/plugins/openapi-router-common/src/example.ts b/plugins/openapi-router-common/src/example.ts
index d2dba3298a..f89fe17e3f 100644
--- a/plugins/openapi-router-common/src/example.ts
+++ b/plugins/openapi-router-common/src/example.ts
@@ -25,14 +25,22 @@ export async function createRouter(
   console.log(options);
   const router = Router() as ApiRouter<DeepWriteable<typeof doc>>;
 
-  router.get('/pets/:uid', (req, res) => {
+  router.get('/pets/:uid', (_, res) => {
     res.json({
       id: 1,
-      name: req.params.uid,
+      name: 'test',
     });
   });
 
-  // router.get('/pet') will complain with a TS error
+  router.get('/pets', (_, res) => {
+    res.json([
+      {
+        id: 1,
+        tag: '123',
+        name: 'test',
+      },
+    ]);
+  });
 
   router.post('/pets', (_, res) => {
     res.send();
diff --git a/plugins/openapi-router-common/src/router.ts b/plugins/openapi-router-common/src/router.ts
index 16b627e62e..68d0c8ecb1 100644
--- a/plugins/openapi-router-common/src/router.ts
+++ b/plugins/openapi-router-common/src/router.ts
@@ -23,17 +23,17 @@ export type DeepWriteable<T> = {
 export interface ApiRouter<Doc extends RequiredDoc> extends Router {
   get: DocRequestMatcher<Doc, this, 'get'>;
 
-  post: DocRequestMatcher<Doc, this, 'get'>;
+  post: DocRequestMatcher<Doc, this, 'post'>;
 
-  all: DocRequestMatcher<Doc, this, 'get'>;
+  all: DocRequestMatcher<Doc, this, 'all'>;
 
-  put: DocRequestMatcher<Doc, this, 'get'>;
+  put: DocRequestMatcher<Doc, this, 'put'>;
 
-  delete: DocRequestMatcher<Doc, this, 'get'>;
+  delete: DocRequestMatcher<Doc, this, 'delete'>;
 
-  patch: DocRequestMatcher<Doc, this, 'get'>;
+  patch: DocRequestMatcher<Doc, this, 'patch'>;
 
-  options: DocRequestMatcher<Doc, this, 'get'>;
+  options: DocRequestMatcher<Doc, this, 'options'>;
 
-  head: DocRequestMatcher<Doc, this, 'get'>;
+  head: DocRequestMatcher<Doc, this, 'head'>;
 }
diff --git a/plugins/openapi-router-common/src/schema/openapi.ts b/plugins/openapi-router-common/src/schema/openapi.ts
new file mode 100644
index 0000000000..8d011ad7a4
--- /dev/null
+++ b/plugins/openapi-router-common/src/schema/openapi.ts
@@ -0,0 +1,1263 @@
+/*
+ * Copyright 2023 The Backstage Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+export default {
+  openapi: '3.1.0',
+  info: {
+    title: '@backstage/plugin-catalog-backend',
+    version: '1',
+    description:
+      'The Backstage backend plugin that provides the Backstage catalog',
+    license: {
+      name: 'Apache-2.0',
+      url: 'http://www.apache.org/licenses/LICENSE-2.0.html',
+    },
+    contact: {},
+  },
+  servers: [
+    {
+      url: '/',
+    },
+  ],
+  components: {
+    examples: {},
+    headers: {},
+    parameters: {},
+    requestBodies: {},
+    responses: {},
+    schemas: {
+      JsonObject: {
+        type: 'object',
+        properties: {},
+        description: 'A type representing all allowed JSON object values.',
+      },
+      MapStringString: {
+        type: 'object',
+        properties: {},
+        additionalProperties: {
+          type: 'string',
+        },
+        description: 'Construct a type with a set of properties K of type T',
+      },
+      EntityLink: {
+        type: 'object',
+        properties: {
+          type: {
+            type: 'string',
+            description:
+              'An optional value to categorize links into specific groups',
+          },
+          icon: {
+            type: 'string',
+            description:
+              'An optional semantic key that represents a visual icon.',
+          },
+          title: {
+            type: 'string',
+            description: 'An optional descriptive title for the link.',
+          },
+          url: {
+            type: 'string',
+            description: 'The url to the external site, document, etc.',
+          },
+        },
+        required: ['url'],
+        description:
+          'A link to external information that is related to the entity.',
+        additionalProperties: false,
+      },
+      EntityMeta: {
+        allOf: [
+          {
+            $ref: '#/components/schemas/JsonObject',
+          },
+          {
+            type: 'object',
+            properties: {
+              links: {
+                type: 'array',
+                items: {
+                  $ref: '#/components/schemas/EntityLink',
+                },
+                description:
+                  'A list of external hyperlinks related to the entity.',
+              },
+              tags: {
+                type: 'array',
+                items: {
+                  type: 'string',
+                },
+                description:
+                  'A list of single-valued strings, to for example classify catalog entities in\nvarious ways.',
+              },
+              annotations: {
+                $ref: '#/components/schemas/MapStringString',
+              },
+              labels: {
+                $ref: '#/components/schemas/MapStringString',
+              },
+              description: {
+                type: 'string',
+                description:
+                  'A short (typically relatively few words, on one line) description of the\nentity.',
+              },
+              title: {
+                type: 'string',
+                description:
+                  'A display name of the entity, to be presented in user interfaces instead\nof the `name` property above, when available.\nThis field is sometimes useful when the `name` is cumbersome or ends up\nbeing perceived as overly technical. The title generally does not have\nas stringent format requirements on it, so it may contain special\ncharacters and be more explanatory. Do keep it very short though, and\navoid situations where a title can be confused with the name of another\nentity, or where two entities share a title.\nNote that this is only for display purposes, and may be ignored by some\nparts of the code. Entity references still always make use of the `name`\nproperty, not the title.',
+              },
+              namespace: {
+                type: 'string',
+                description: 'The namespace that the entity belongs to.',
+              },
+              name: {
+                type: 'string',
+                description:
+                  'The name of the entity.\nMust be unique within the catalog at any given point in time, for any\ngiven namespace + kind pair. This value is part of the technical\nidentifier of the entity, and as such it will appear in URLs, database\ntables, entity references, and similar. It is subject to restrictions\nregarding what characters are allowed.\nIf you want to use a different, more human readable string with fewer\nrestrictions on it in user interfaces, see the `title` field below.',
+              },
+              etag: {
+                type: 'string',
+                description:
+                  'An opaque string that changes for each update operation to any part of\nthe entity, including metadata.\nThis field can not be set by the user at creation time, and the server\nwill reject an attempt to do so. The field will be populated in read\noperations. The field can (optionally) be specified when performing\nupdate or delete operations, and the server will then reject the\noperation if it does not match the current stored value.',
+              },
+              uid: {
+                type: 'string',
+                description:
+                  'A globally unique ID for the entity.\nThis field can not be set by the user at creation time, and the server\nwill reject an attempt to do so. The field will be populated in read\noperations. The field can (optionally) be specified when performing\nupdate or delete operations, but the server is free to reject requests\nthat do so in such a way that it breaks semantics.',
+              },
+            },
+            required: ['name'],
+          },
+        ],
+        description: 'Metadata fields common to all versions/kinds of entity.',
+        additionalProperties: false,
+      },
+      EntityRelation: {
+        type: 'object',
+        properties: {
+          targetRef: {
+            type: 'string',
+            description: 'The entity ref of the target of this relation.',
+          },
+          type: {
+            type: 'string',
+            description: 'The type of the relation.',
+          },
+        },
+        required: ['targetRef', 'type'],
+        description:
+          'A relation of a specific type to another entity in the catalog.',
+        additionalProperties: false,
+      },
+      Entity: {
+        type: 'object',
+        properties: {
+          relations: {
+            type: 'array',
+            items: {
+              $ref: '#/components/schemas/EntityRelation',
+            },
+            description:
+              'The relations that this entity has with other entities.',
+          },
+          spec: {
+            $ref: '#/components/schemas/JsonObject',
+          },
+          metadata: {
+            $ref: '#/components/schemas/EntityMeta',
+          },
+          kind: {
+            type: 'string',
+            description: 'The high level entity type being described.',
+          },
+          apiVersion: {
+            type: 'string',
+            description:
+              'The version of specification format for this particular entity that\nthis is written against.',
+          },
+        },
+        required: ['metadata', 'kind', 'apiVersion'],
+        description:
+          "The parts of the format that's common to all versions/kinds of entity.",
+        additionalProperties: false,
+      },
+      EntityAncestryResponse: {
+        type: 'object',
+        properties: {
+          items: {
+            type: 'array',
+            items: {
+              type: 'object',
+              properties: {
+                parentEntityRefs: {
+                  items: {
+                    type: 'string',
+                  },
+                  type: 'array',
+                },
+                entity: {
+                  $ref: '#/components/schemas/Entity',
+                },
+              },
+              required: ['parentEntityRefs', 'entity'],
+            },
+          },
+          rootEntityRef: {
+            type: 'string',
+          },
+        },
+        required: ['items', 'rootEntityRef'],
+        additionalProperties: false,
+      },
+      EntitiesBatchResponse: {
+        type: 'object',
+        properties: {
+          items: {
+            type: 'array',
+            items: {
+              allOf: [
+                {
+                  $ref: '#/components/schemas/Entity',
+                },
+              ],
+              nullable: true,
+            },
+            description:
+              'The list of entities, in the same order as the refs in the request. Entries\nthat are null signify that no entity existed with that ref.',
+          },
+        },
+        required: ['items'],
+        additionalProperties: false,
+      },
+      EntityFacet: {
+        type: 'object',
+        properties: {
+          value: {
+            type: 'string',
+          },
+          count: {
+            type: 'number',
+          },
+        },
+        additionalProperties: false,
+      },
+      EntityFacets: {
+        type: 'array',
+        items: {
+          $ref: '#/components/schemas/EntityFacet',
+        },
+      },
+      EntityFacetsResponse: {
+        type: 'object',
+        properties: {
+          facets: {
+            type: 'object',
+            additionalProperties: {
+              $ref: '#/components/schemas/EntityFacets',
+            },
+          },
+        },
+        required: ['facets'],
+        additionalProperties: false,
+      },
+      Location: {
+        type: 'object',
+        properties: {
+          target: {
+            type: 'string',
+          },
+          type: {
+            type: 'string',
+          },
+          id: {
+            type: 'string',
+          },
+        },
+        required: ['target', 'type', 'id'],
+        description: 'Entity location for a specific entity.',
+        additionalProperties: false,
+      },
+      LocationSpec: {
+        type: 'object',
+        properties: {
+          presence: {
+            type: 'string',
+            enum: ['optional', 'required'],
+          },
+          target: {
+            type: 'string',
+          },
+          type: {
+            type: 'string',
+          },
+        },
+        required: ['target', 'type'],
+        description: 'Holds the entity location information.',
+        additionalProperties: false,
+      },
+      AnalyzeLocationExistingEntity: {
+        type: 'object',
+        properties: {
+          entity: {
+            $ref: '#/components/schemas/Entity',
+          },
+          isRegistered: {
+            type: 'boolean',
+          },
+          location: {
+            $ref: '#/components/schemas/LocationSpec',
+          },
+        },
+        required: ['entity', 'isRegistered', 'location'],
+        description:
+          "If the folder pointed to already contained catalog info yaml files, they are\nread and emitted like this so that the frontend can inform the user that it\nlocated them and can make sure to register them as well if they weren't\nalready",
+        additionalProperties: false,
+      },
+      RecursivePartialEntityRelation: {
+        type: 'object',
+        properties: {
+          targetRef: {
+            type: 'string',
+            description: 'The entity ref of the target of this relation.',
+          },
+          type: {
+            type: 'string',
+            description: 'The type of the relation.',
+          },
+        },
+        description:
+          'A relation of a specific type to another entity in the catalog.',
+        additionalProperties: false,
+      },
+      RecursivePartialEntityMeta: {
+        allOf: [
+          {
+            $ref: '#/components/schemas/JsonObject',
+          },
+          {
+            type: 'object',
+            properties: {
+              properties: null,
+              links: {
+                type: 'array',
+                items: {
+                  $ref: '#/components/schemas/EntityLink',
+                },
+                description:
+                  'A list of external hyperlinks related to the entity.',
+              },
+              tags: {
+                type: 'array',
+                items: {
+                  type: 'string',
+                },
+                description:
+                  'A list of single-valued strings, to for example classify catalog entities in\nvarious ways.',
+              },
+              annotations: {
+                $ref: '#/components/schemas/MapStringString',
+              },
+              labels: {
+                $ref: '#/components/schemas/MapStringString',
+              },
+              description: {
+                type: 'string',
+                description:
+                  'A short (typically relatively few words, on one line) description of the\nentity.',
+              },
+              title: {
+                type: 'string',
+                description:
+                  'A display name of the entity, to be presented in user interfaces instead\nof the `name` property above, when available.\nThis field is sometimes useful when the `name` is cumbersome or ends up\nbeing perceived as overly technical. The title generally does not have\nas stringent format requirements on it, so it may contain special\ncharacters and be more explanatory. Do keep it very short though, and\navoid situations where a title can be confused with the name of another\nentity, or where two entities share a title.\nNote that this is only for display purposes, and may be ignored by some\nparts of the code. Entity references still always make use of the `name`\nproperty, not the title.',
+              },
+              namespace: {
+                type: 'string',
+                description: 'The namespace that the entity belongs to.',
+              },
+              name: {
+                type: 'string',
+                description:
+                  'The name of the entity.\nMust be unique within the catalog at any given point in time, for any\ngiven namespace + kind pair. This value is part of the technical\nidentifier of the entity, and as such it will appear in URLs, database\ntables, entity references, and similar. It is subject to restrictions\nregarding what characters are allowed.\nIf you want to use a different, more human readable string with fewer\nrestrictions on it in user interfaces, see the `title` field below.',
+              },
+              etag: {
+                type: 'string',
+                description:
+                  'An opaque string that changes for each update operation to any part of\nthe entity, including metadata.\nThis field can not be set by the user at creation time, and the server\nwill reject an attempt to do so. The field will be populated in read\noperations. The field can (optionally) be specified when performing\nupdate or delete operations, and the server will then reject the\noperation if it does not match the current stored value.',
+              },
+              uid: {
+                type: 'string',
+                description:
+                  'A globally unique ID for the entity.\nThis field can not be set by the user at creation time, and the server\nwill reject an attempt to do so. The field will be populated in read\noperations. The field can (optionally) be specified when performing\nupdate or delete operations, but the server is free to reject requests\nthat do so in such a way that it breaks semantics.',
+              },
+            },
+            description:
+              'Metadata fields common to all versions/kinds of entity.',
+          },
+        ],
+        additionalProperties: false,
+      },
+      RecursivePartial_Entity_: {
+        type: 'object',
+        properties: {
+          apiVersion: {
+            type: 'string',
+            description:
+              'The version of specification format for this particular entity that\nthis is written against.',
+          },
+          kind: {
+            type: 'string',
+            description: 'The high level entity type being described.',
+          },
+          metadata: {
+            $ref: '#/components/schemas/RecursivePartialEntityMeta',
+          },
+          spec: {
+            $ref: '#/components/schemas/JsonObject',
+          },
+          relations: {
+            type: 'array',
+            items: {
+              $ref: '#/components/schemas/RecursivePartialEntityRelation',
+            },
+            description:
+              'The relations that this entity has with other entities.',
+          },
+        },
+        description: 'Makes all keys of an entire hierarchy optional.',
+        additionalProperties: false,
+      },
+      AnalyzeLocationEntityField: {
+        type: 'object',
+        properties: {
+          description: {
+            type: 'string',
+            description:
+              'A text to show to the user to inform about the choices made. Like, it could say\n"Found a CODEOWNERS file that covers this target, so we suggest leaving this \nfield empty; which would currently make it owned by X" where X is taken from the\ncodeowners file.',
+          },
+          value: {
+            type: 'string',
+            nullable: true,
+          },
+          state: {
+            type: 'string',
+            enum: [
+              'analysisSuggestedValue',
+              'analysisSuggestedNoValue',
+              'needsUserInput',
+            ],
+            description:
+              'The outcome of the analysis for this particular field',
+          },
+          field: {
+            type: 'string',
+            description:
+              'e.g. "spec.owner"? The frontend needs to know how to "inject" the field into the\nentity again if the user wants to change it',
+          },
+        },
+        required: ['description', 'value', 'state', 'field'],
+        additionalProperties: false,
+      },
+      AnalyzeLocationGenerateEntity: {
+        type: 'object',
+        properties: {
+          fields: {
+            type: 'array',
+            items: {
+              $ref: '#/components/schemas/AnalyzeLocationEntityField',
+            },
+          },
+          entity: {
+            $ref: '#/components/schemas/RecursivePartial_Entity_',
+          },
+        },
+        required: ['fields', 'entity'],
+        description:
+          "This is some form of representation of what the analyzer could deduce.\nWe should probably have a chat about how this can best be conveyed to\nthe frontend. It'll probably contain a (possibly incomplete) entity, plus\nenough info for the frontend to know what form data to show to the user\nfor overriding/completing the info.",
+        additionalProperties: false,
+      },
+      AnalyzeLocationResponse: {
+        type: 'object',
+        properties: {
+          generateEntities: {
+            items: {
+              $ref: '#/components/schemas/AnalyzeLocationGenerateEntity',
+            },
+            type: 'array',
+          },
+          existingEntityFiles: {
+            items: {
+              $ref: '#/components/schemas/AnalyzeLocationExistingEntity',
+            },
+            type: 'array',
+          },
+        },
+        required: ['generateEntities', 'existingEntityFiles'],
+        additionalProperties: false,
+      },
+      LocationInput: {
+        type: 'object',
+        properties: {
+          type: {
+            type: 'string',
+          },
+          target: {
+            type: 'string',
+          },
+          presence: {
+            type: 'string',
+            enum: ['optional', 'required'],
+          },
+        },
+        required: ['type', 'target', 'presence'],
+        additionalProperties: false,
+      },
+      SerializedError: {
+        allOf: [
+          {
+            $ref: '#/components/schemas/JsonObject',
+          },
+          {
+            type: 'object',
+            properties: {
+              code: {
+                type: 'string',
+                description:
+                  'A custom code (not necessarily the same as an HTTP response code); may not be present',
+              },
+              stack: {
+                type: 'string',
+                description: 'A stringified stack trace; may not be present',
+              },
+              message: {
+                type: 'string',
+                description: 'The message of the exception that was thrown',
+              },
+              name: {
+                type: 'string',
+                description: 'The name of the exception that was thrown',
+              },
+            },
+            required: ['message', 'name'],
+          },
+        ],
+        description: 'The serialized form of an Error.',
+        additionalProperties: false,
+      },
+      EntitiesQueryResponse: {
+        type: 'object',
+        properties: {
+          items: {
+            type: 'array',
+            items: {
+              $ref: '#/components/schemas/Entity',
+            },
+            description: 'The list of entities paginated by a specific filter.',
+          },
+          totalItems: {
+            type: 'number',
+          },
+          pageInfo: {
+            type: 'object',
+            properties: {
+              nextCursor: {
+                type: 'string',
+                description: 'Base64 encoded database query for the next page.',
+              },
+              prevCursor: {
+                type: 'string',
+                description:
+                  'Base64 encoded database query for the previous page.',
+              },
+            },
+          },
+        },
+        additionalProperties: false,
+      },
+    },
+    securitySchemes: {
+      JWT: {
+        type: 'http',
+        scheme: 'bearer',
+        bearerFormat: 'JWT',
+      },
+    },
+  },
+  paths: {
+    '/refresh': {
+      post: {
+        operationId: 'RefreshEntity',
+        responses: {
+          '200': {
+            description: 'Refreshed',
+          },
+        },
+        security: [
+          {},
+          {
+            JWT: [],
+          },
+        ],
+        parameters: [],
+        requestBody: {
+          required: true,
+          content: {
+            'application/json': {
+              schema: {
+                type: 'object',
+                properties: {
+                  authorizationToken: {
+                    type: 'string',
+                  },
+                  entityRef: {
+                    type: 'string',
+                    description:
+                      'The reference to a single entity that should be refreshed',
+                  },
+                },
+                required: ['entityRef'],
+                description:
+                  'Options for requesting a refresh of entities in the catalog.',
+                additionalProperties: false,
+              },
+            },
+          },
+        },
+      },
+    },
+    '/entities': {
+      get: {
+        operationId: 'GetEntities',
+        responses: {
+          '200': {
+            description: '',
+            content: {
+              'application/json': {
+                schema: {
+                  type: 'array',
+                  items: {
+                    $ref: '#/components/schemas/Entity',
+                  },
+                },
+              },
+            },
+          },
+        },
+        security: [
+          {},
+          {
+            JWT: [],
+          },
+        ],
+        parameters: [
+          {
+            in: 'query',
+            name: 'filter',
+            required: false,
+            schema: {
+              type: 'string',
+            },
+          },
+          {
+            in: 'query',
+            name: 'fields',
+            required: false,
+            schema: {
+              type: 'string',
+            },
+          },
+          {
+            in: 'query',
+            name: 'offset',
+            required: false,
+            schema: {
+              type: 'string',
+            },
+          },
+          {
+            in: 'query',
+            name: 'limit',
+            required: false,
+            schema: {
+              type: 'string',
+            },
+          },
+          {
+            in: 'query',
+            name: 'after',
+            required: false,
+            schema: {
+              type: 'string',
+            },
+          },
+        ],
+      },
+    },
+    '/entities/by-uid/{uid}': {
+      get: {
+        operationId: 'GetEntityByUid',
+        responses: {
+          '200': {
+            description: 'Ok',
+            content: {
+              'application/json': {
+                schema: {
+                  $ref: '#/components/schemas/Entity',
+                },
+              },
+            },
+          },
+        },
+        security: [
+          {},
+          {
+            JWT: [],
+          },
+        ],
+        parameters: [
+          {
+            in: 'path',
+            name: 'uid',
+            required: true,
+            schema: {
+              type: 'string',
+            },
+          },
+        ],
+      },
+      delete: {
+        operationId: 'DeleteEntityByUid',
+        responses: {
+          '204': {
+            description: 'Deleted successfully.',
+          },
+        },
+        security: [
+          {},
+          {
+            JWT: [],
+          },
+        ],
+        parameters: [
+          {
+            in: 'path',
+            name: 'uid',
+            required: true,
+            schema: {
+              type: 'string',
+            },
+          },
+        ],
+      },
+    },
+    '/entities/by-name/{kind}/{namespace}/{name}': {
+      get: {
+        operationId: 'GetEntityByName',
+        responses: {
+          '200': {
+            description: 'Ok',
+            content: {
+              'application/json': {
+                schema: {
+                  $ref: '#/components/schemas/Entity',
+                },
+              },
+            },
+          },
+        },
+        security: [
+          {},
+          {
+            JWT: [],
+          },
+        ],
+        parameters: [
+          {
+            in: 'path',
+            name: 'kind',
+            required: true,
+            schema: {
+              type: 'string',
+            },
+          },
+          {
+            in: 'path',
+            name: 'namespace',
+            required: true,
+            schema: {
+              type: 'string',
+            },
+          },
+          {
+            in: 'path',
+            name: 'name',
+            required: true,
+            schema: {
+              type: 'string',
+            },
+          },
+        ],
+      },
+    },
+    '/entities/by-name/{kind}/{namespace}/{name}/ancestry': {
+      get: {
+        operationId: 'GetEntityAncestryByName',
+        responses: {
+          '200': {
+            description: 'Ok',
+            content: {
+              'application/json': {
+                schema: {
+                  $ref: '#/components/schemas/EntityAncestryResponse',
+                },
+              },
+            },
+          },
+        },
+        security: [
+          {},
+          {
+            JWT: [],
+          },
+        ],
+        parameters: [
+          {
+            in: 'path',
+            name: 'kind',
+            required: true,
+            schema: {
+              type: 'string',
+            },
+          },
+          {
+            in: 'path',
+            name: 'namespace',
+            required: true,
+            schema: {
+              type: 'string',
+            },
+          },
+          {
+            in: 'path',
+            name: 'name',
+            required: true,
+            schema: {
+              type: 'string',
+            },
+          },
+        ],
+      },
+    },
+    '/entities/by-refs': {
+      post: {
+        operationId: 'GetEntitiesByRefs',
+        responses: {
+          '200': {
+            description: 'Ok',
+            content: {
+              'application/json': {
+                schema: {
+                  $ref: '#/components/schemas/EntitiesBatchResponse',
+                },
+              },
+            },
+          },
+        },
+        security: [
+          {},
+          {
+            JWT: [],
+          },
+        ],
+        parameters: [
+          {
+            in: 'query',
+            name: 'fields',
+            required: false,
+            schema: {
+              type: 'string',
+            },
+          },
+        ],
+        requestBody: {
+          required: true,
+          content: {
+            'application/json': {
+              schema: {
+                type: 'array',
+                items: {
+                  type: 'string',
+                },
+              },
+            },
+          },
+        },
+      },
+    },
+    '/entities/by-query': {
+      get: {
+        operationId: 'GetEntitiesByQuery',
+        responses: {
+          '200': {
+            description: 'Ok',
+            content: {
+              'application/json': {
+                schema: {
+                  $ref: '#/components/schemas/EntitiesQueryResponse',
+                },
+              },
+            },
+          },
+        },
+        security: [
+          {},
+          {
+            JWT: [],
+          },
+        ],
+        parameters: [
+          {
+            in: 'query',
+            name: 'fields',
+            required: false,
+            schema: {
+              type: 'string',
+            },
+          },
+        ],
+        requestBody: {
+          required: true,
+          content: {
+            'application/json': {
+              schema: {
+                type: 'array',
+                items: {
+                  type: 'string',
+                },
+              },
+            },
+          },
+        },
+      },
+    },
+    '/entity-facets': {
+      get: {
+        operationId: 'GetEntityFacets',
+        responses: {
+          '200': {
+            description: 'Ok',
+            content: {
+              'application/json': {
+                schema: {
+                  $ref: '#/components/schemas/EntityFacetsResponse',
+                },
+              },
+            },
+          },
+        },
+        security: [
+          {},
+          {
+            JWT: [],
+          },
+        ],
+        parameters: [
+          {
+            in: 'query',
+            name: 'facet',
+            required: true,
+            schema: {
+              type: 'string',
+            },
+          },
+          {
+            in: 'query',
+            name: 'filter',
+            required: false,
+            schema: {
+              type: 'string',
+            },
+          },
+        ],
+      },
+    },
+    '/locations': {
+      post: {
+        operationId: 'CreateLocation',
+        responses: {
+          '200': {
+            description: 'Ok',
+            content: {
+              'application/json': {
+                schema: {
+                  type: 'object',
+                  properties: {
+                    exists: {
+                      type: 'boolean',
+                    },
+                    entities: {
+                      items: {
+                        $ref: '#/components/schemas/Entity',
+                      },
+                      type: 'array',
+                    },
+                    location: {
+                      $ref: '#/components/schemas/Location',
+                    },
+                  },
+                  required: ['entities', 'location'],
+                },
+              },
+            },
+          },
+        },
+        security: [
+          {},
+          {
+            JWT: [],
+          },
+        ],
+        parameters: [
+          {
+            in: 'query',
+            name: 'dryRun',
+            required: false,
+            schema: {
+              type: 'boolean',
+            },
+          },
+        ],
+        requestBody: {
+          required: true,
+          content: {
+            'application/json': {
+              schema: {
+                type: 'object',
+                properties: {
+                  presence: {
+                    type: 'string',
+                    enum: ['required', 'optional'],
+                  },
+                  target: {
+                    type: 'string',
+                  },
+                  type: {
+                    type: 'string',
+                  },
+                },
+                required: ['presence', 'target', 'type'],
+              },
+            },
+          },
+        },
+      },
+      get: {
+        operationId: 'GetLocations',
+        responses: {
+          '200': {
+            description: 'Ok',
+            content: {
+              'application/json': {
+                schema: {
+                  type: 'array',
+                  items: {
+                    type: 'object',
+                    properties: {
+                      data: {
+                        $ref: '#/components/schemas/Location',
+                      },
+                    },
+                    required: ['data'],
+                  },
+                },
+              },
+            },
+          },
+        },
+        security: [
+          {},
+          {
+            JWT: [],
+          },
+        ],
+        parameters: [],
+      },
+    },
+    '/locations/{id}': {
+      get: {
+        operationId: 'GetLocation',
+        responses: {
+          '200': {
+            description: 'Ok',
+            content: {
+              'application/json': {
+                schema: {
+                  $ref: '#/components/schemas/Location',
+                },
+              },
+            },
+          },
+        },
+        security: [
+          {},
+          {
+            JWT: [],
+          },
+        ],
+        parameters: [
+          {
+            in: 'path',
+            name: 'id',
+            required: true,
+            schema: {
+              type: 'string',
+            },
+          },
+        ],
+      },
+      delete: {
+        operationId: 'DeleteLocation',
+        responses: {
+          '204': {
+            description: 'No content',
+          },
+        },
+        security: [
+          {},
+          {
+            JWT: [],
+          },
+        ],
+        parameters: [
+          {
+            in: 'path',
+            name: 'id',
+            required: true,
+            schema: {
+              type: 'string',
+            },
+          },
+        ],
+      },
+    },
+    '/analyze-location': {
+      post: {
+        operationId: 'AnalyzeLocation',
+        responses: {
+          '200': {
+            description: 'Ok',
+            content: {
+              'application/json': {
+                schema: {
+                  $ref: '#/components/schemas/AnalyzeLocationResponse',
+                },
+              },
+            },
+          },
+        },
+        security: [
+          {},
+          {
+            JWT: [],
+          },
+        ],
+        parameters: [],
+        requestBody: {
+          required: true,
+          content: {
+            'application/json': {
+              schema: {
+                type: 'object',
+                properties: {
+                  catalogFileName: {
+                    type: 'string',
+                  },
+                  location: {
+                    $ref: '#/components/schemas/LocationInput',
+                  },
+                },
+                required: ['catalogFileName', 'location'],
+              },
+            },
+          },
+        },
+      },
+    },
+    '/validate-entity': {
+      post: {
+        operationId: 'ValidateEntity',
+        responses: {
+          '200': {
+            description: 'Ok',
+            content: {
+              'application/json': {
+                schema: {
+                  anyOf: [
+                    {
+                      type: 'object',
+                      properties: {
+                        errors: {
+                          $ref: '#/components/schemas/SerializedError',
+                        },
+                      },
+                      required: ['errors'],
+                    },
+                    {
+                      type: 'object',
+                      properties: {
+                        errors: {
+                          type: 'array',
+                          items: {
+                            $ref: '#/components/schemas/SerializedError',
+                          },
+                        },
+                      },
+                      required: ['errors'],
+                    },
+                  ],
+                },
+              },
+            },
+          },
+        },
+        security: [
+          {},
+          {
+            JWT: [],
+          },
+        ],
+        parameters: [],
+        requestBody: {
+          required: true,
+          content: {
+            'application/json': {
+              schema: {
+                type: 'object',
+                properties: {
+                  location: {
+                    type: 'string',
+                  },
+                  entity: {
+                    $ref: '#/components/schemas/Entity',
+                  },
+                },
+                required: ['location', 'entity'],
+              },
+            },
+          },
+        },
+      },
+    },
+  },
+} as const;
diff --git a/plugins/openapi-router-common/src/schema/petstore.ts b/plugins/openapi-router-common/src/schema/petstore.ts
index 308e3925e0..a79a3efe4d 100644
--- a/plugins/openapi-router-common/src/schema/petstore.ts
+++ b/plugins/openapi-router-common/src/schema/petstore.ts
@@ -156,6 +156,7 @@ export default {
             type: 'string',
           },
         },
+        additionalProperties: false,
       },
       Pets: {
         type: 'array',
@@ -175,6 +176,7 @@ export default {
             type: 'string',
           },
         },
+        additionalProperties: false,
       },
     },
   },
diff --git a/plugins/openapi-router-common/src/types/common.ts b/plugins/openapi-router-common/src/types/common.ts
index 834f1b49f5..ff404cb126 100644
--- a/plugins/openapi-router-common/src/types/common.ts
+++ b/plugins/openapi-router-common/src/types/common.ts
@@ -131,7 +131,7 @@ export type ObjectWithContentSchema<
   Object extends { content?: ContentObject },
 > = Object['content'] extends ContentObject
   ? SchemaRef<Doc, Object['content']['application/json']['schema']>
-  : unknown;
+  : never;
 
 /**
  * From https://stackoverflow.com/questions/71393738/typescript-intersection-not-union-type-from-json-schema.
@@ -164,3 +164,7 @@ export type ConvertAll<T, R extends ReadonlyArray<unknown> = []> = T extends [
 ]
   ? ConvertAll<Rest, [...R, FromSchema<First>]>
   : R;
+
+type UnknownIfNever<P> = [P] extends [never] ? unknown : P;
+
+export type ToTypeSafe<T> = UnknownIfNever<ConvertAll<TuplifyUnion<T>>[number]>;
diff --git a/plugins/openapi-router-common/src/types/express.ts b/plugins/openapi-router-common/src/types/express.ts
index 055235af99..dc7bf61832 100644
--- a/plugins/openapi-router-common/src/types/express.ts
+++ b/plugins/openapi-router-common/src/types/express.ts
@@ -13,7 +13,6 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-import { Application } from 'express';
 import core from 'express-serve-static-core';
 import { DocPathTemplate, MethodAwareDocPath, RequiredDoc } from './common';
 import { RequestBodyToJsonSchema } from './requests';
@@ -60,12 +59,8 @@ export interface DocRequestMatcher<
     | 'delete'
     | 'patch'
     | 'options'
-    | 'head' = any,
+    | 'head',
 > {
-  <Path extends MethodAwareDocPath<Doc, DocPathTemplate<Doc>, Method>>(
-    path: Path,
-    ...handlers: DocRequestHandler<Doc, Path, Method>[]
-  ): T;
   <Path extends MethodAwareDocPath<Doc, DocPathTemplate<Doc>, Method>>(
     path: Path,
     ...handlers: Array<DocRequestHandler<Doc, Path, Method>>
@@ -74,13 +69,4 @@ export interface DocRequestMatcher<
     path: Path,
     ...handlers: Array<DocRequestHandlerParams<Doc, Path, Method>>
   ): T;
-  <Path extends MethodAwareDocPath<Doc, DocPathTemplate<Doc>, Method>>(
-    path: PathParams,
-    ...handlers: Array<DocRequestHandler<Doc, Path, Method>>
-  ): T;
-  <Path extends MethodAwareDocPath<Doc, DocPathTemplate<Doc>, Method>>(
-    path: PathParams,
-    ...handlers: Array<DocRequestHandlerParams<Doc, Path, Method>>
-  ): T;
-  (path: PathParams, subApplication: Application): T;
 }
diff --git a/plugins/openapi-router-common/src/types/requests.ts b/plugins/openapi-router-common/src/types/requests.ts
index ae05a27537..6964f219a2 100644
--- a/plugins/openapi-router-common/src/types/requests.ts
+++ b/plugins/openapi-router-common/src/types/requests.ts
@@ -29,9 +29,7 @@ import type {
   DocPathMethod,
   DocPathTemplate,
   PathTemplate,
-  ConvertAll,
-  TuplifyUnion,
-  ValueOf,
+  ToTypeSafe,
 } from './common';
 
 type RequestBody<
@@ -54,12 +52,10 @@ export type RequestBodySchema<
   Method extends DocPathMethod<Doc, Path>,
 > = RequestBody<Doc, DocPath<Doc, Path>, Method> extends RequestBodyObject
   ? ObjectWithContentSchema<Doc, RequestBody<Doc, DocPath<Doc, Path>, Method>>
-  : unknown;
+  : never;
 
 export type RequestBodyToJsonSchema<
   Doc extends RequiredDoc,
   Path extends PathTemplate<Extract<keyof Doc['paths'], string>>,
   Method extends DocPathMethod<Doc, Path>,
-> = ConvertAll<
-  TuplifyUnion<ValueOf<RequestBodySchema<Doc, Path, Method>>>
->[number];
+> = ToTypeSafe<RequestBodySchema<Doc, Path, Method>>;
diff --git a/plugins/openapi-router-common/src/types/response.ts b/plugins/openapi-router-common/src/types/response.ts
index 5c01a70673..f20d94c2a9 100644
--- a/plugins/openapi-router-common/src/types/response.ts
+++ b/plugins/openapi-router-common/src/types/response.ts
@@ -29,9 +29,8 @@ import type {
   DocPathMethod,
   DocPathTemplate,
   PathTemplate,
-  ConvertAll,
+  ToTypeSafe,
   ValueOf,
-  TuplifyUnion,
 } from './common';
 
 type Response<
@@ -85,13 +84,11 @@ export type ResponseSchemas<
         Doc,
         Responses<Doc, DocPath<Doc, Path>, Method>[StatusCode]
       >
-    : unknown;
+    : never;
 };
 
 export type ResponseBodyToJsonSchema<
   Doc extends RequiredDoc,
   Path extends PathTemplate<Extract<keyof Doc['paths'], string>>,
   Method extends DocPathMethod<Doc, Path>,
-> = ConvertAll<
-  TuplifyUnion<ValueOf<ResponseSchemas<Doc, Path, Method>>>
->[number];
+> = ToTypeSafe<ValueOf<ResponseSchemas<Doc, Path, Method>>>;

From 43e6ea1c41bc0f0d3743562c276729b2ce630ba2 Mon Sep 17 00:00:00 2001
From: Aramis Sennyey <sennyeya@amazon.com>
Date: Wed, 22 Feb 2023 17:19:57 -0500
Subject: [PATCH 12/61] Duplicate issue.

Signed-off-by: Aramis Sennyey <sennyeya@amazon.com>
---
 yarn.lock | 13 ++-----------
 1 file changed, 2 insertions(+), 11 deletions(-)

diff --git a/yarn.lock b/yarn.lock
index a3a011d2ca..334b0306fc 100644
--- a/yarn.lock
+++ b/yarn.lock
@@ -3690,16 +3690,7 @@ __metadata:
   languageName: node
   linkType: hard
 
-"@babel/runtime@npm:^7.0.0, @babel/runtime@npm:^7.1.2, @babel/runtime@npm:^7.10.1, @babel/runtime@npm:^7.12.1, @babel/runtime@npm:^7.12.5, @babel/runtime@npm:^7.14.6, @babel/runtime@npm:^7.15.4, @babel/runtime@npm:^7.18.6, @babel/runtime@npm:^7.2.0, @babel/runtime@npm:^7.20.1, @babel/runtime@npm:^7.20.7, @babel/runtime@npm:^7.3.1, @babel/runtime@npm:^7.4.4, @babel/runtime@npm:^7.5.5, @babel/runtime@npm:^7.6.0, @babel/runtime@npm:^7.7.6, @babel/runtime@npm:^7.8.3, @babel/runtime@npm:^7.8.4, @babel/runtime@npm:^7.8.7, @babel/runtime@npm:^7.9.2":
-  version: 7.20.13
-  resolution: "@babel/runtime@npm:7.20.13"
-  dependencies:
-    regenerator-runtime: ^0.13.11
-  checksum: 09b7a97a05c80540db6c9e4ddf8c5d2ebb06cae5caf3a87e33c33f27f8c4d49d9c67a2d72f1570e796045288fad569f98a26ceba0c4f5fad2af84b6ad855c4fb
-  languageName: node
-  linkType: hard
-
-"@babel/runtime@npm:^7.18.3":
+"@babel/runtime@npm:^7.0.0, @babel/runtime@npm:^7.1.2, @babel/runtime@npm:^7.10.1, @babel/runtime@npm:^7.12.1, @babel/runtime@npm:^7.12.5, @babel/runtime@npm:^7.14.6, @babel/runtime@npm:^7.15.4, @babel/runtime@npm:^7.18.3, @babel/runtime@npm:^7.18.6, @babel/runtime@npm:^7.2.0, @babel/runtime@npm:^7.20.1, @babel/runtime@npm:^7.20.7, @babel/runtime@npm:^7.3.1, @babel/runtime@npm:^7.4.4, @babel/runtime@npm:^7.5.5, @babel/runtime@npm:^7.6.0, @babel/runtime@npm:^7.7.6, @babel/runtime@npm:^7.8.3, @babel/runtime@npm:^7.8.4, @babel/runtime@npm:^7.8.7, @babel/runtime@npm:^7.9.2":
   version: 7.21.0
   resolution: "@babel/runtime@npm:7.21.0"
   dependencies:
@@ -20774,7 +20765,7 @@ __metadata:
   languageName: node
   linkType: hard
 
-"content-type@npm:^1.0.4":
+"content-type@npm:^1.0.4, content-type@npm:~1.0.4":
   version: 1.0.5
   resolution: "content-type@npm:1.0.5"
   checksum: 566271e0a251642254cde0f845f9dd4f9856e52d988f4eb0d0dcffbb7a1f8ec98de7a5215fc628f3bce30fe2fb6fd2bc064b562d721658c59b544e2d34ea2766

From 7eabd155efa216797ad83b08a66aa2209d184b99 Mon Sep 17 00:00:00 2001
From: Aramis Sennyey <sennyeya@amazon.com>
Date: Wed, 22 Feb 2023 17:20:53 -0500
Subject: [PATCH 13/61] Fix yarn dedupe weirdness.

Signed-off-by: Aramis Sennyey <sennyeya@amazon.com>
---
 yarn.lock | 21 +++++++++++++++------
 1 file changed, 15 insertions(+), 6 deletions(-)

diff --git a/yarn.lock b/yarn.lock
index 334b0306fc..df5fb881d4 100644
--- a/yarn.lock
+++ b/yarn.lock
@@ -3690,7 +3690,16 @@ __metadata:
   languageName: node
   linkType: hard
 
-"@babel/runtime@npm:^7.0.0, @babel/runtime@npm:^7.1.2, @babel/runtime@npm:^7.10.1, @babel/runtime@npm:^7.12.1, @babel/runtime@npm:^7.12.5, @babel/runtime@npm:^7.14.6, @babel/runtime@npm:^7.15.4, @babel/runtime@npm:^7.18.3, @babel/runtime@npm:^7.18.6, @babel/runtime@npm:^7.2.0, @babel/runtime@npm:^7.20.1, @babel/runtime@npm:^7.20.7, @babel/runtime@npm:^7.3.1, @babel/runtime@npm:^7.4.4, @babel/runtime@npm:^7.5.5, @babel/runtime@npm:^7.6.0, @babel/runtime@npm:^7.7.6, @babel/runtime@npm:^7.8.3, @babel/runtime@npm:^7.8.4, @babel/runtime@npm:^7.8.7, @babel/runtime@npm:^7.9.2":
+"@babel/runtime@npm:^7.0.0, @babel/runtime@npm:^7.1.2, @babel/runtime@npm:^7.10.1, @babel/runtime@npm:^7.12.1, @babel/runtime@npm:^7.12.5, @babel/runtime@npm:^7.14.6, @babel/runtime@npm:^7.15.4, @babel/runtime@npm:^7.18.6, @babel/runtime@npm:^7.2.0, @babel/runtime@npm:^7.20.1, @babel/runtime@npm:^7.20.7, @babel/runtime@npm:^7.3.1, @babel/runtime@npm:^7.4.4, @babel/runtime@npm:^7.5.5, @babel/runtime@npm:^7.6.0, @babel/runtime@npm:^7.7.6, @babel/runtime@npm:^7.8.3, @babel/runtime@npm:^7.8.4, @babel/runtime@npm:^7.8.7, @babel/runtime@npm:^7.9.2":
+  version: 7.20.13
+  resolution: "@babel/runtime@npm:7.20.13"
+  dependencies:
+    regenerator-runtime: ^0.13.11
+  checksum: 09b7a97a05c80540db6c9e4ddf8c5d2ebb06cae5caf3a87e33c33f27f8c4d49d9c67a2d72f1570e796045288fad569f98a26ceba0c4f5fad2af84b6ad855c4fb
+  languageName: node
+  linkType: hard
+
+"@babel/runtime@npm:^7.18.3":
   version: 7.21.0
   resolution: "@babel/runtime@npm:7.21.0"
   dependencies:
@@ -20765,7 +20774,7 @@ __metadata:
   languageName: node
   linkType: hard
 
-"content-type@npm:^1.0.4, content-type@npm:~1.0.4":
+"content-type@npm:^1.0.4":
   version: 1.0.5
   resolution: "content-type@npm:1.0.5"
   checksum: 566271e0a251642254cde0f845f9dd4f9856e52d988f4eb0d0dcffbb7a1f8ec98de7a5215fc628f3bce30fe2fb6fd2bc064b562d721658c59b544e2d34ea2766
@@ -40987,10 +40996,10 @@ __metadata:
   languageName: node
   linkType: hard
 
-"yaml@npm:^2.0.0, yaml@npm:^2.1.1, yaml@npm:^2.1.3, yaml@npm:^2.2.1":
-  version: 2.2.1
-  resolution: "yaml@npm:2.2.1"
-  checksum: 84f68cbe462d5da4e7ded4a8bded949ffa912bc264472e5a684c3d45b22d8f73a3019963a32164023bdf3d83cfb6f5b58ff7b2b10ef5b717c630f40bd6369a23
+"yaml@npm:^2.0.0, yaml@npm:^2.1.1, yaml@npm:^2.1.3":
+  version: 2.1.3
+  resolution: "yaml@npm:2.1.3"
+  checksum: 91316062324a93f9cb547469092392e7d004ff8f70c40fecb420f042a4870b2181557350da56c92f07bd44b8f7a252b0be26e6ade1f548e1f4351bdd01c9d3c7
   languageName: node
   linkType: hard
 

From aff3349f26888d953def2c4e33cf52319df84a47 Mon Sep 17 00:00:00 2001
From: Aramis Sennyey <sennyeya@amazon.com>
Date: Wed, 22 Feb 2023 17:21:53 -0500
Subject: [PATCH 14/61] Remove express-openapi.

Signed-off-by: Aramis Sennyey <sennyeya@amazon.com>
---
 plugins/catalog-backend/package.json |   1 -
 yarn.lock                            | 187 ++++-----------------------
 2 files changed, 27 insertions(+), 161 deletions(-)

diff --git a/plugins/catalog-backend/package.json b/plugins/catalog-backend/package.json
index df5560459b..ef6fdd8029 100644
--- a/plugins/catalog-backend/package.json
+++ b/plugins/catalog-backend/package.json
@@ -66,7 +66,6 @@
     "codeowners-utils": "^1.0.2",
     "core-js": "^3.6.5",
     "express": "^4.17.1",
-    "express-openapi": "^12.1.0",
     "express-promise-router": "^4.1.0",
     "fast-json-stable-stringify": "^2.1.0",
     "fs-extra": "10.1.0",
diff --git a/yarn.lock b/yarn.lock
index df5fb881d4..48309e9b1d 100644
--- a/yarn.lock
+++ b/yarn.lock
@@ -5729,7 +5729,6 @@ __metadata:
     codeowners-utils: ^1.0.2
     core-js: ^3.6.5
     express: ^4.17.1
-    express-openapi: ^12.1.0
     express-promise-router: ^4.1.0
     fast-json-stable-stringify: ^2.1.0
     fs-extra: 10.1.0
@@ -17972,7 +17971,7 @@ __metadata:
   languageName: node
   linkType: hard
 
-"ajv-formats@npm:^2.0.2, ajv-formats@npm:^2.1.0, ajv-formats@npm:^2.1.1":
+"ajv-formats@npm:^2.1.1":
   version: 2.1.1
   resolution: "ajv-formats@npm:2.1.1"
   dependencies:
@@ -18030,6 +18029,18 @@ __metadata:
   languageName: node
   linkType: hard
 
+"ajv@npm:^8.0.0, ajv@npm:^8.10.0, ajv@npm:^8.12.0, ajv@npm:^8.8.0":
+  version: 8.12.0
+  resolution: "ajv@npm:8.12.0"
+  dependencies:
+    fast-deep-equal: ^3.1.1
+    json-schema-traverse: ^1.0.0
+    require-from-string: ^2.0.2
+    uri-js: ^4.2.2
+  checksum: 4dc13714e316e67537c8b31bc063f99a1d9d9a497eb4bbd55191ac0dcd5e4985bbb71570352ad6f1e76684fb6d790928f96ba3b2d4fd6e10024be9612fe3f001
+  languageName: node
+  linkType: hard
+
 "alphanum-sort@npm:^1.0.2":
   version: 1.0.2
   resolution: "alphanum-sort@npm:1.0.2"
@@ -20774,13 +20785,6 @@ __metadata:
   languageName: node
   linkType: hard
 
-"content-type@npm:^1.0.4":
-  version: 1.0.5
-  resolution: "content-type@npm:1.0.5"
-  checksum: 566271e0a251642254cde0f845f9dd4f9856e52d988f4eb0d0dcffbb7a1f8ec98de7a5215fc628f3bce30fe2fb6fd2bc064b562d721658c59b544e2d34ea2766
-  languageName: node
-  linkType: hard
-
 "content-type@npm:~1.0.4":
   version: 1.0.4
   resolution: "content-type@npm:1.0.4"
@@ -22183,15 +22187,6 @@ __metadata:
   languageName: node
   linkType: hard
 
-"difunc@npm:0.0.4":
-  version: 0.0.4
-  resolution: "difunc@npm:0.0.4"
-  dependencies:
-    esprima: ^4.0.0
-  checksum: 19b850dae20cba3bdf238b85fa90f79526974e7634348a3157eef3da6eb161e7f43142aa531f6be61eed1235d1f4b6a16e07912f313b5afcceee56d998c2e300
-  languageName: node
-  linkType: hard
-
 "dir-glob@npm:^3.0.1":
   version: 3.0.1
   resolution: "dir-glob@npm:3.0.1"
@@ -24092,24 +24087,6 @@ __metadata:
   languageName: node
   linkType: hard
 
-"express-normalize-query-params-middleware@npm:^0.5.0":
-  version: 0.5.1
-  resolution: "express-normalize-query-params-middleware@npm:0.5.1"
-  checksum: 20fef3a200c452cbfef25f738e8ed44704ad30f04899cce21d3984b74e4fcbeefdc5dcec3aed1a0e4e54f231c55f3cba2c3d0cc3faebfea0cab437a852bca09b
-  languageName: node
-  linkType: hard
-
-"express-openapi@npm:^12.1.0":
-  version: 12.1.0
-  resolution: "express-openapi@npm:12.1.0"
-  dependencies:
-    express-normalize-query-params-middleware: ^0.5.0
-    openapi-framework: ^12.1.0
-    openapi-types: ^12.1.0
-  checksum: 6b87b7990891b1f4d4bd3e071eddd72d7433ae770d5ad0cfbbee234a0d4e712150640ec15d8fe9d1af99b49209700c58f4694045f00bd380a569a86ba5008755
-  languageName: node
-  linkType: hard
-
 "express-prom-bundle@npm:^6.3.6":
   version: 6.6.0
   resolution: "express-prom-bundle@npm:6.6.0"
@@ -25007,15 +24984,6 @@ __metadata:
   languageName: node
   linkType: hard
 
-"fs-routes@npm:^12.0.0":
-  version: 12.0.0
-  resolution: "fs-routes@npm:12.0.0"
-  peerDependencies:
-    glob: ">=7.1.6"
-  checksum: 4e97b08584c4ee04cf00215ac5175ba6f3aeaa4fb254cd108149d675edffcf90e802ead9965a5252271f26e1a47b31c341b41e209b9d210b2a584ae2a642c466
-  languageName: node
-  linkType: hard
-
 "fs.realpath@npm:^1.0.0":
   version: 1.0.0
   resolution: "fs.realpath@npm:1.0.0"
@@ -25337,19 +25305,6 @@ __metadata:
   languageName: node
   linkType: hard
 
-"glob@npm:*, glob@npm:^8.0.0, glob@npm:^8.0.1, glob@npm:^8.0.3":
-  version: 8.1.0
-  resolution: "glob@npm:8.1.0"
-  dependencies:
-    fs.realpath: ^1.0.0
-    inflight: ^1.0.4
-    inherits: 2
-    minimatch: ^5.0.1
-    once: ^1.3.0
-  checksum: 92fbea3221a7d12075f26f0227abac435de868dd0736a17170663783296d0dd8d3d532a5672b4488a439bf5d7fb85cdd07c11185d6cd39184f0385cbdfb86a47
-  languageName: node
-  linkType: hard
-
 "glob@npm:7.1.6":
   version: 7.1.6
   resolution: "glob@npm:7.1.6"
@@ -25391,6 +25346,19 @@ __metadata:
   languageName: node
   linkType: hard
 
+"glob@npm:^8.0.0, glob@npm:^8.0.1, glob@npm:^8.0.3":
+  version: 8.1.0
+  resolution: "glob@npm:8.1.0"
+  dependencies:
+    fs.realpath: ^1.0.0
+    inflight: ^1.0.4
+    inherits: 2
+    minimatch: ^5.0.1
+    once: ^1.3.0
+  checksum: 92fbea3221a7d12075f26f0227abac435de868dd0736a17170663783296d0dd8d3d532a5672b4488a439bf5d7fb85cdd07c11185d6cd39184f0385cbdfb86a47
+  languageName: node
+  linkType: hard
+
 "global-agent@npm:^3.0.0":
   version: 3.0.0
   resolution: "global-agent@npm:3.0.0"
@@ -27023,13 +26991,6 @@ __metadata:
   languageName: node
   linkType: hard
 
-"is-dir@npm:^1.0.0":
-  version: 1.0.0
-  resolution: "is-dir@npm:1.0.0"
-  checksum: b81430f22d03318b144391ec9633abdd6fdcd8fd02509bee1ab5a20b79311505ba4344282d2cab565114779ac36626fd034168b9bd47c3be12d956ae2ca76a5c
-  languageName: node
-  linkType: hard
-
 "is-docker@npm:^2.0.0, is-docker@npm:^2.1.1":
   version: 2.2.1
   resolution: "is-docker@npm:2.2.1"
@@ -29811,7 +29772,7 @@ __metadata:
   languageName: node
   linkType: hard
 
-"lodash.merge@npm:^4.6.1, lodash.merge@npm:^4.6.2":
+"lodash.merge@npm:^4.6.2":
   version: 4.6.2
   resolution: "lodash.merge@npm:4.6.2"
   checksum: ad580b4bdbb7ca1f7abf7e1bce63a9a0b98e370cf40194b03380a46b4ed799c9573029599caebc1b14e3f24b111aef72b96674a56cfa105e0f5ac70546cdc005
@@ -32375,79 +32336,6 @@ __metadata:
   languageName: node
   linkType: hard
 
-"openapi-default-setter@npm:^12.1.0":
-  version: 12.1.0
-  resolution: "openapi-default-setter@npm:12.1.0"
-  dependencies:
-    openapi-types: ^12.1.0
-  checksum: 3b4543d7c091134690fcfc986258481b6211f17b4322552764b3a4a9725784202bc17419a524302dd1187ecea556dea4f2cb525f4a0258c2ab5ddec884bf00e2
-  languageName: node
-  linkType: hard
-
-"openapi-framework@npm:^12.1.0":
-  version: 12.1.0
-  resolution: "openapi-framework@npm:12.1.0"
-  dependencies:
-    difunc: 0.0.4
-    fs-routes: ^12.0.0
-    glob: "*"
-    is-dir: ^1.0.0
-    js-yaml: ^3.10.0
-    openapi-default-setter: ^12.1.0
-    openapi-request-coercer: ^12.1.0
-    openapi-request-validator: ^12.1.0
-    openapi-response-validator: ^12.1.0
-    openapi-schema-validator: ^12.1.0
-    openapi-security-handler: ^12.1.0
-    openapi-types: ^12.1.0
-    ts-log: ^2.1.4
-  checksum: 4cbb35e2870604c91c01f397aa2ea8fb072f648acb9a47b830d0d67c1e68bb75eadc3e97bcbe2ea994b7374ba38866b6d91734df6e2481ce42e6625d66ccc5bd
-  languageName: node
-  linkType: hard
-
-"openapi-jsonschema-parameters@npm:^12.1.0":
-  version: 12.1.0
-  resolution: "openapi-jsonschema-parameters@npm:12.1.0"
-  dependencies:
-    openapi-types: ^12.1.0
-  checksum: 9465549e132d02ad4be67326e22c9a2e3f0cf19ffa0e3c1fe69a542a675707f11c33080836b0eebd75c02501dbcb5f4130fa446d470ede3ba67b7c52e1bc341f
-  languageName: node
-  linkType: hard
-
-"openapi-request-coercer@npm:^12.1.0":
-  version: 12.1.0
-  resolution: "openapi-request-coercer@npm:12.1.0"
-  dependencies:
-    openapi-types: ^12.1.0
-    ts-log: ^2.1.4
-  checksum: 4359d4fd58b032146838aabb9762fc2ac01771e7bea4679af5a241964f3df15ddced7968e6a8d419954d166e93ad32e08f530da0d9a8483d3c4d97be7c7c848c
-  languageName: node
-  linkType: hard
-
-"openapi-request-validator@npm:^12.1.0":
-  version: 12.1.0
-  resolution: "openapi-request-validator@npm:12.1.0"
-  dependencies:
-    ajv: ^8.3.0
-    ajv-formats: ^2.1.0
-    content-type: ^1.0.4
-    openapi-jsonschema-parameters: ^12.1.0
-    openapi-types: ^12.1.0
-    ts-log: ^2.1.4
-  checksum: 794b1c15dbf04107ede7b8304e5b7c2fa183ad0c4bd65b3e0ee4d415cf508324932959f661120f1bfb58a23d88b5458dc0db868bc36f9ec44ea03b99ea9d42df
-  languageName: node
-  linkType: hard
-
-"openapi-response-validator@npm:^12.1.0":
-  version: 12.1.0
-  resolution: "openapi-response-validator@npm:12.1.0"
-  dependencies:
-    ajv: ^8.4.0
-    openapi-types: ^12.1.0
-  checksum: f07036661ac846c5d508b423d01039cd5bd33d564e053fdc039046f964fad71b03a7c9254195b1d5a8a1912fcc45dce13616af97c445c6d7b040c825e1f91de1
-  languageName: node
-  linkType: hard
-
 "openapi-sampler@npm:^1.2.1":
   version: 1.2.1
   resolution: "openapi-sampler@npm:1.2.1"
@@ -32458,27 +32346,6 @@ __metadata:
   languageName: node
   linkType: hard
 
-"openapi-schema-validator@npm:^12.1.0":
-  version: 12.1.0
-  resolution: "openapi-schema-validator@npm:12.1.0"
-  dependencies:
-    ajv: ^8.1.0
-    ajv-formats: ^2.0.2
-    lodash.merge: ^4.6.1
-    openapi-types: ^12.1.0
-  checksum: 1008ef82910cc30e85132c041b269a4cc2991dad17e2d7c4cddbfb5641a15e934016bc4d1bab32f2dc79f7f3673b82b655c3634838c9ce3a8f497af3be762aa5
-  languageName: node
-  linkType: hard
-
-"openapi-security-handler@npm:^12.1.0":
-  version: 12.1.0
-  resolution: "openapi-security-handler@npm:12.1.0"
-  dependencies:
-    openapi-types: ^12.1.0
-  checksum: 07f645300fdc0ca5d01790fb77e01d8e537f6b0439f55ec9af5097d3dd044e3e0fc55ce0acb9551f04256819d7738f8c3d468645e581f7b0487648eed428d519
-  languageName: node
-  linkType: hard
-
 "openapi-types@npm:^12.0.0, openapi-types@npm:^12.1.0":
   version: 12.1.0
   resolution: "openapi-types@npm:12.1.0"

From 6e4ac33a60dd867446b5eb818f03087e0d5d5405 Mon Sep 17 00:00:00 2001
From: Aramis Sennyey <sennyeya@amazon.com>
Date: Wed, 22 Feb 2023 17:32:09 -0500
Subject: [PATCH 15/61] Duplicate fix?

Signed-off-by: Aramis Sennyey <sennyeya@amazon.com>
---
 yarn.lock | 20 ++------------------
 1 file changed, 2 insertions(+), 18 deletions(-)

diff --git a/yarn.lock b/yarn.lock
index 48309e9b1d..495b14b40f 100644
--- a/yarn.lock
+++ b/yarn.lock
@@ -3690,16 +3690,7 @@ __metadata:
   languageName: node
   linkType: hard
 
-"@babel/runtime@npm:^7.0.0, @babel/runtime@npm:^7.1.2, @babel/runtime@npm:^7.10.1, @babel/runtime@npm:^7.12.1, @babel/runtime@npm:^7.12.5, @babel/runtime@npm:^7.14.6, @babel/runtime@npm:^7.15.4, @babel/runtime@npm:^7.18.6, @babel/runtime@npm:^7.2.0, @babel/runtime@npm:^7.20.1, @babel/runtime@npm:^7.20.7, @babel/runtime@npm:^7.3.1, @babel/runtime@npm:^7.4.4, @babel/runtime@npm:^7.5.5, @babel/runtime@npm:^7.6.0, @babel/runtime@npm:^7.7.6, @babel/runtime@npm:^7.8.3, @babel/runtime@npm:^7.8.4, @babel/runtime@npm:^7.8.7, @babel/runtime@npm:^7.9.2":
-  version: 7.20.13
-  resolution: "@babel/runtime@npm:7.20.13"
-  dependencies:
-    regenerator-runtime: ^0.13.11
-  checksum: 09b7a97a05c80540db6c9e4ddf8c5d2ebb06cae5caf3a87e33c33f27f8c4d49d9c67a2d72f1570e796045288fad569f98a26ceba0c4f5fad2af84b6ad855c4fb
-  languageName: node
-  linkType: hard
-
-"@babel/runtime@npm:^7.18.3":
+"@babel/runtime@npm:^7.0.0, @babel/runtime@npm:^7.1.2, @babel/runtime@npm:^7.10.1, @babel/runtime@npm:^7.12.1, @babel/runtime@npm:^7.12.5, @babel/runtime@npm:^7.14.6, @babel/runtime@npm:^7.15.4, @babel/runtime@npm:^7.18.3, @babel/runtime@npm:^7.18.6, @babel/runtime@npm:^7.2.0, @babel/runtime@npm:^7.20.1, @babel/runtime@npm:^7.20.7, @babel/runtime@npm:^7.3.1, @babel/runtime@npm:^7.4.4, @babel/runtime@npm:^7.5.5, @babel/runtime@npm:^7.6.0, @babel/runtime@npm:^7.7.6, @babel/runtime@npm:^7.8.3, @babel/runtime@npm:^7.8.4, @babel/runtime@npm:^7.8.7, @babel/runtime@npm:^7.9.2":
   version: 7.21.0
   resolution: "@babel/runtime@npm:7.21.0"
   dependencies:
@@ -40863,14 +40854,7 @@ __metadata:
   languageName: node
   linkType: hard
 
-"yaml@npm:^2.0.0, yaml@npm:^2.1.1, yaml@npm:^2.1.3":
-  version: 2.1.3
-  resolution: "yaml@npm:2.1.3"
-  checksum: 91316062324a93f9cb547469092392e7d004ff8f70c40fecb420f042a4870b2181557350da56c92f07bd44b8f7a252b0be26e6ade1f548e1f4351bdd01c9d3c7
-  languageName: node
-  linkType: hard
-
-"yaml@npm:^2.2.1":
+"yaml@npm:^2.0.0, yaml@npm:^2.1.1, yaml@npm:^2.1.3, yaml@npm:^2.2.1":
   version: 2.2.1
   resolution: "yaml@npm:2.2.1"
   checksum: 84f68cbe462d5da4e7ded4a8bded949ffa912bc264472e5a684c3d45b22d8f73a3019963a32164023bdf3d83cfb6f5b58ff7b2b10ef5b717c630f40bd6369a23

From 2ae752b91e8152b6b867d00788e93b6e2d5f3b41 Mon Sep 17 00:00:00 2001
From: Aramis Sennyey <sennyeya@amazon.com>
Date: Wed, 22 Feb 2023 17:34:03 -0500
Subject: [PATCH 16/61] Add dependency.

Signed-off-by: Aramis Sennyey <sennyeya@amazon.com>
---
 plugins/openapi-router-common/package.json | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/plugins/openapi-router-common/package.json b/plugins/openapi-router-common/package.json
index 3c0857a5c7..ee8858848f 100644
--- a/plugins/openapi-router-common/package.json
+++ b/plugins/openapi-router-common/package.json
@@ -30,6 +30,7 @@
     "dist"
   ],
   "dependencies": {
+    "@backstage/backend-common": "workspace:^",
     "express": "^4.17.1",
     "json-schema-to-ts": "^2.6.2",
     "openapi-types": "^12.1.0",
@@ -38,4 +39,4 @@
     "winston": "^3.8.2",
     "yn": "^4.0.0"
   }
-}
+}
\ No newline at end of file

From 20b79e8110b8a9c69ee2ec2c353668e4aaa4af95 Mon Sep 17 00:00:00 2001
From: Aramis Sennyey <sennyeya@amazon.com>
Date: Wed, 22 Feb 2023 17:42:21 -0500
Subject: [PATCH 17/61] More fixes to the yarn.lock file.

Signed-off-by: Aramis Sennyey <sennyeya@amazon.com>
---
 plugins/openapi-router-common/package.json | 2 +-
 yarn.lock                                  | 1 +
 2 files changed, 2 insertions(+), 1 deletion(-)

diff --git a/plugins/openapi-router-common/package.json b/plugins/openapi-router-common/package.json
index ee8858848f..c121084abc 100644
--- a/plugins/openapi-router-common/package.json
+++ b/plugins/openapi-router-common/package.json
@@ -39,4 +39,4 @@
     "winston": "^3.8.2",
     "yn": "^4.0.0"
   }
-}
\ No newline at end of file
+}
diff --git a/yarn.lock b/yarn.lock
index 495b14b40f..5d2931cc57 100644
--- a/yarn.lock
+++ b/yarn.lock
@@ -7798,6 +7798,7 @@ __metadata:
   version: 0.0.0-use.local
   resolution: "@backstage/plugin-openapi-router@workspace:plugins/openapi-router-common"
   dependencies:
+    "@backstage/backend-common": "workspace:^"
     "@backstage/cli": "workspace:^"
     express: ^4.17.1
     json-schema-to-ts: ^2.6.2

From a71d26fabf3331ba824b6a3da87b2d308646c029 Mon Sep 17 00:00:00 2001
From: Aramis Sennyey <sennyeya@amazon.com>
Date: Wed, 22 Feb 2023 18:32:53 -0500
Subject: [PATCH 18/61] Create + update API report.

Signed-off-by: Aramis Sennyey <sennyeya@amazon.com>
---
 plugins/openapi-router-common/api-report.md   | 331 ++++++++++++++++++
 plugins/openapi-router-common/src/index.ts    |   3 +-
 plugins/openapi-router-common/src/router.ts   |  12 +-
 .../openapi-router-common/src/types/common.ts |  88 ++++-
 .../src/types/express.ts                      |  22 +-
 .../openapi-router-common/src/types/index.ts  |   2 +
 .../src/types/requests.ts                     |  12 +-
 .../src/types/{response.ts => responses.ts}   |  20 +-
 8 files changed, 467 insertions(+), 23 deletions(-)
 create mode 100644 plugins/openapi-router-common/api-report.md
 rename plugins/openapi-router-common/src/types/{response.ts => responses.ts} (92%)

diff --git a/plugins/openapi-router-common/api-report.md b/plugins/openapi-router-common/api-report.md
new file mode 100644
index 0000000000..6dbe59dc06
--- /dev/null
+++ b/plugins/openapi-router-common/api-report.md
@@ -0,0 +1,331 @@
+## API Report File for "@backstage/plugin-openapi-router"
+
+> Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.com/).
+
+```ts
+import type { ContentObject } from 'openapi3-ts';
+import core from 'express-serve-static-core';
+import { FromSchema } from 'json-schema-to-ts';
+import { JSONSchema7 } from 'json-schema-to-ts';
+import type { OpenAPIObject } from 'openapi3-ts';
+import type { ReferenceObject } from 'openapi3-ts';
+import type { RequestBodyObject } from 'openapi3-ts';
+import type { ResponseObject } from 'openapi3-ts';
+import { Router } from 'express';
+
+// @public
+export interface ApiRouter<Doc extends RequiredDoc> extends Router {
+  // (undocumented)
+  all: DocRequestMatcher<Doc, this, 'all'>;
+  // (undocumented)
+  delete: DocRequestMatcher<Doc, this, 'delete'>;
+  // (undocumented)
+  get: DocRequestMatcher<Doc, this, 'get'>;
+  // (undocumented)
+  head: DocRequestMatcher<Doc, this, 'head'>;
+  // (undocumented)
+  options: DocRequestMatcher<Doc, this, 'options'>;
+  // (undocumented)
+  patch: DocRequestMatcher<Doc, this, 'patch'>;
+  // (undocumented)
+  post: DocRequestMatcher<Doc, this, 'post'>;
+  // (undocumented)
+  put: DocRequestMatcher<Doc, this, 'put'>;
+}
+
+// @public (undocumented)
+export type ComponentRef<
+  Doc extends RequiredDoc,
+  Type extends ComponentTypes<Doc>,
+  Ref extends ReferenceObject,
+> = Ref extends {
+  $ref: `#/components/${Type}/${infer Name}`;
+}
+  ? Name extends keyof Doc['components'][Type]
+    ? Doc['components'][Type][Name] extends ReferenceObject
+      ? ComponentRef<Doc, Type, Doc['components'][Type][Name]>
+      : Doc['components'][Type][Name]
+    : never
+  : never;
+
+// @public (undocumented)
+export type ComponentTypes<Doc extends RequiredDoc> = Extract<
+  keyof Doc['components'],
+  string
+>;
+
+// @public (undocumented)
+export type ConvertAll<T, R extends ReadonlyArray<unknown> = []> = T extends [
+  infer First extends JSONSchema7,
+  ...infer Rest,
+]
+  ? ConvertAll<Rest, [...R, FromSchema<First>]>
+  : R;
+
+// @public (undocumented)
+export type DocOperation<
+  Doc extends RequiredDoc,
+  Path extends keyof Doc['paths'],
+  Method extends keyof Doc['paths'][Path],
+> = Doc['paths'][Path][Method];
+
+// @public
+export type DocPath<
+  Doc extends PathDoc,
+  Path extends PathTemplate<Extract<keyof Doc['paths'], string>>,
+> = ValueOf<{
+  [Template in Extract<
+    keyof Doc['paths'],
+    string
+  >]: Path extends PathTemplate<Template> ? Template : never;
+}>;
+
+// @public (undocumented)
+export type DocPathMethod<
+  Doc extends Pick<RequiredDoc, 'paths'>,
+  Path extends DocPathTemplate<Doc>,
+> = keyof Doc['paths'][DocPath<Doc, Path>];
+
+// @public (undocumented)
+export type DocPathTemplate<Doc extends PathDoc> = PathTemplate<
+  Extract<keyof Doc['paths'], string>
+>;
+
+// @public
+export type DocRequestHandler<
+  Doc extends RequiredDoc,
+  Path extends DocPathTemplate<Doc>,
+  Method extends keyof Doc['paths'][Path],
+> = core.RequestHandler<
+  core.ParamsDictionary,
+  ResponseBodyToJsonSchema<Doc, Path, Method>,
+  RequestBodyToJsonSchema<Doc, Path, Method>,
+  ParsedQs,
+  Record<string, string>
+>;
+
+// @public
+export type DocRequestHandlerParams<
+  Doc extends RequiredDoc,
+  Path extends DocPathTemplate<Doc>,
+  Method extends keyof Doc['paths'][Path],
+> = core.RequestHandlerParams<
+  core.ParamsDictionary,
+  ResponseBodyToJsonSchema<Doc, Path, Method>,
+  RequestBodyToJsonSchema<Doc, Path, Method>,
+  ParsedQs,
+  Record<string, string>
+>;
+
+// @public
+export interface DocRequestMatcher<
+  Doc extends RequiredDoc,
+  T,
+  Method extends
+    | 'all'
+    | 'get'
+    | 'post'
+    | 'put'
+    | 'delete'
+    | 'patch'
+    | 'options'
+    | 'head',
+> {
+  // (undocumented)
+  <Path extends MethodAwareDocPath<Doc, DocPathTemplate<Doc>, Method>>(
+    path: Path,
+    ...handlers: Array<DocRequestHandler<Doc, Path, Method>>
+  ): T;
+  // (undocumented)
+  <Path extends MethodAwareDocPath<Doc, DocPathTemplate<Doc>, Method>>(
+    path: Path,
+    ...handlers: Array<DocRequestHandlerParams<Doc, Path, Method>>
+  ): T;
+}
+
+// @public (undocumented)
+export type LastOf<T> = UnionToIntersection<
+  T extends any ? () => T : never
+> extends () => infer R
+  ? R
+  : never;
+
+// @public (undocumented)
+export type MethodAwareDocPath<
+  Doc extends PathDoc,
+  Path extends PathTemplate<Extract<keyof Doc['paths'], string>>,
+  Method extends keyof Doc['paths'][Path],
+> = ValueOf<{
+  [Template in Extract<
+    keyof Doc['paths'],
+    string
+  >]: Path extends PathTemplate<Template>
+    ? Method extends DocPathMethod<Doc, Path>
+      ? PathTemplate<Template>
+      : never
+    : never;
+}>;
+
+// @public (undocumented)
+export type ObjectWithContentSchema<
+  Doc extends RequiredDoc,
+  Object extends {
+    content?: ContentObject;
+  },
+> = Object['content'] extends ContentObject
+  ? SchemaRef<Doc, Object['content']['application/json']['schema']>
+  : never;
+
+// @public
+export interface ParsedQs {
+  // (undocumented)
+  [key: string]: undefined | string | string[] | ParsedQs | ParsedQs[];
+}
+
+// @public (undocumented)
+export type PathDoc = Pick<OpenAPIObject, 'paths'>;
+
+// @public
+export type PathTemplate<Path extends string> =
+  Path extends `${infer Prefix}{${string}}${infer Suffix}`
+    ? `${Prefix}${string}${PathTemplate<Suffix>}`
+    : Path;
+
+// @public (undocumented)
+export type Push<T extends any[], V> = [...T, V];
+
+// @public (undocumented)
+export type RequestBody<
+  Doc extends RequiredDoc,
+  Path extends Extract<keyof Doc['paths'], string>,
+  Method extends keyof Doc['paths'][Path],
+> = DocOperation<Doc, Path, Method>['requestBody'] extends ReferenceObject
+  ? 'requestBodies' extends ComponentTypes<Doc>
+    ? ComponentRef<
+        Doc,
+        'requestBodies',
+        DocOperation<Doc, Path, Method>['requestBody']
+      >
+    : never
+  : DocOperation<Doc, Path, Method>['requestBody'];
+
+// @public (undocumented)
+export type RequestBodySchema<
+  Doc extends RequiredDoc,
+  Path extends DocPathTemplate<Doc>,
+  Method extends DocPathMethod<Doc, Path>,
+> = RequestBody<Doc, DocPath<Doc, Path>, Method> extends RequestBodyObject
+  ? ObjectWithContentSchema<Doc, RequestBody<Doc, DocPath<Doc, Path>, Method>>
+  : never;
+
+// @public
+export type RequestBodyToJsonSchema<
+  Doc extends RequiredDoc,
+  Path extends PathTemplate<Extract<keyof Doc['paths'], string>>,
+  Method extends DocPathMethod<Doc, Path>,
+> = ToTypeSafe<RequestBodySchema<Doc, Path, Method>>;
+
+// @public
+export type RequiredDoc = Pick<OpenAPIObject, 'paths' | 'components'>;
+
+// @public (undocumented)
+type Response_2<
+  Doc extends RequiredDoc,
+  Path extends keyof Doc['paths'],
+  Method extends keyof Doc['paths'][Path],
+  StatusCode extends keyof Doc['paths'][Path]['responses'],
+> = DocOperation<
+  Doc,
+  Path,
+  Method
+>['responses'][StatusCode] extends ReferenceObject
+  ? 'responses' extends ComponentTypes<Doc>
+    ? ComponentRef<
+        Doc,
+        'responses',
+        DocOperation<Doc, Path, Method>['responses'][StatusCode]
+      >
+    : never
+  : DocOperation<Doc, Path, Method>['responses'][StatusCode];
+export { Response_2 as Response };
+
+// @public
+export type ResponseBodyToJsonSchema<
+  Doc extends RequiredDoc,
+  Path extends PathTemplate<Extract<keyof Doc['paths'], string>>,
+  Method extends DocPathMethod<Doc, Path>,
+> = ToTypeSafe<ValueOf<ResponseSchemas<Doc, Path, Method>>>;
+
+// @public (undocumented)
+export type Responses<
+  Doc extends RequiredDoc,
+  Path extends keyof Doc['paths'],
+  Method extends keyof Doc['paths'][Path],
+> = {
+  [StatusCode in keyof DocOperation<
+    Doc,
+    Path,
+    Method
+  >['responses']]: Response_2<Doc, Path, Method, StatusCode>;
+};
+
+// @public (undocumented)
+export type ResponseSchema<
+  Doc extends RequiredDoc,
+  Object extends ResponseObject,
+> = ObjectWithContentSchema<Doc, Object>;
+
+// @public (undocumented)
+export type ResponseSchemas<
+  Doc extends RequiredDoc,
+  Path extends DocPathTemplate<Doc>,
+  Method extends DocPathMethod<Doc, Path>,
+> = {
+  [StatusCode in keyof Responses<Doc, DocPath<Doc, Path>, Method>]: Responses<
+    Doc,
+    DocPath<Doc, Path>,
+    Method
+  >[StatusCode] extends ResponseObject
+    ? ResponseSchema<
+        Doc,
+        Responses<Doc, DocPath<Doc, Path>, Method>[StatusCode]
+      >
+    : never;
+};
+
+// @public (undocumented)
+export type SchemaRef<Doc extends RequiredDoc, Schema> = Schema extends {
+  $ref: `#/components/schemas/${infer Name}`;
+}
+  ? 'schemas' extends keyof Doc['components']
+    ? Name extends keyof Doc['components']['schemas']
+      ? SchemaRef<Doc, Doc['components']['schemas'][Name]>
+      : never
+    : never
+  : {
+      [Key in keyof Schema]: SchemaRef<Doc, Schema[Key]>;
+    };
+
+// @public (undocumented)
+export type ToTypeSafe<T> = UnknownIfNever<ConvertAll<TuplifyUnion<T>>[number]>;
+
+// @public (undocumented)
+export type TuplifyUnion<
+  T,
+  L = LastOf<T>,
+  N = [T] extends [never] ? true : false,
+> = true extends N ? [] : Push<TuplifyUnion<Exclude<T, L>>, L>;
+
+// @public
+export type UnionToIntersection<U> = (
+  U extends any ? (k: U) => void : never
+) extends (k: infer I) => void
+  ? I
+  : never;
+
+// @public (undocumented)
+export type UnknownIfNever<P> = [P] extends [never] ? unknown : P;
+
+// @public
+export type ValueOf<T> = T[keyof T];
+```
diff --git a/plugins/openapi-router-common/src/index.ts b/plugins/openapi-router-common/src/index.ts
index 7edca76f93..3aab4ab1d1 100644
--- a/plugins/openapi-router-common/src/index.ts
+++ b/plugins/openapi-router-common/src/index.ts
@@ -20,4 +20,5 @@
  * @packageDocumentation
  */
 
-export * from './router';
+export type { ApiRouter } from './router';
+export * from './types';
diff --git a/plugins/openapi-router-common/src/router.ts b/plugins/openapi-router-common/src/router.ts
index 68d0c8ecb1..417ffb157f 100644
--- a/plugins/openapi-router-common/src/router.ts
+++ b/plugins/openapi-router-common/src/router.ts
@@ -14,12 +14,20 @@
  * limitations under the License.
  */
 import { Router } from 'express';
-import { RequiredDoc } from './types';
-import { DocRequestMatcher } from './types/express';
+import { RequiredDoc, DocRequestMatcher } from './types';
 
+/**
+ * Helper to transform readonly `as const` API specs for the ApiRouter.
+ * @public
+ */
 export type DeepWriteable<T> = {
   -readonly [P in keyof T]: DeepWriteable<T[P]>;
 };
+
+/**
+ * Typed Express router based on an OpenAPI 3.1 spec.
+ * @public
+ */
 export interface ApiRouter<Doc extends RequiredDoc> extends Router {
   get: DocRequestMatcher<Doc, this, 'get'>;
 
diff --git a/plugins/openapi-router-common/src/types/common.ts b/plugins/openapi-router-common/src/types/common.ts
index ff404cb126..62f9a7bcee 100644
--- a/plugins/openapi-router-common/src/types/common.ts
+++ b/plugins/openapi-router-common/src/types/common.ts
@@ -25,21 +25,37 @@ import type {
   ReferenceObject,
 } from 'openapi3-ts';
 
+/**
+ * Basic OpenAPI spec with paths and components properties enforced.
+ *
+ * @public
+ */
 export type RequiredDoc = Pick<OpenAPIObject, 'paths' | 'components'>;
 
+/**
+ * @public
+ */
 export type PathDoc = Pick<OpenAPIObject, 'paths'>;
 
 /**
  * Get value types of `T`
+ *
+ * @public
  */
 export type ValueOf<T> = T[keyof T];
 
 /**
- * Validate a string against OpenAPI path template
- * ```
+ * Validate a string against OpenAPI path template, {@link https://spec.openapis.org/oas/v3.1.0#path-templating-matching}.
+ *
+ * @example
+ * ```ts
  * const path = PathTemplate<"/posts/{postId}/comments/{commentId}"> = "/posts/1/comments/2"const pathWithParams: PathTemplate<"/posts/{postId}/comments/{commentId}"> = "/posts/1/comments/2";
- * const pathWithoutParams: PathTemplate<"/posts/comments"> = "/posts/comments";```
- * https://spec.openapis.org/oas/v3.1.0#path-templating-matching
+ * const pathWithoutParams: PathTemplate<"/posts/comments"> = "/posts/comments";
+ * ```
+ *
+ *
+ *
+ * @public
  */
 export type PathTemplate<Path extends string> =
   Path extends `${infer Prefix}{${string}}${infer Suffix}`
@@ -48,7 +64,8 @@ export type PathTemplate<Path extends string> =
 
 /**
  * Extract path as specified in OpenAPI `Doc` based on request path
- * ```
+ * @example
+ * ```ts
  * const spec = {
  *   paths: {
  *       "/posts/{postId}/comments/{commentId}": {},
@@ -58,6 +75,8 @@ export type PathTemplate<Path extends string> =
  * const specPathWithParams: DocPath<typeof spec, "/posts/1/comments/2"> = "/posts/{postId}/comments/{commentId}";
  * const specPathWithoutParams: DocPath<typeof spec, "/posts/comments"> = "/posts/comments";
  * ```
+ *
+ * @public
  */
 export type DocPath<
   Doc extends PathDoc,
@@ -69,15 +88,24 @@ export type DocPath<
   >]: Path extends PathTemplate<Template> ? Template : never;
 }>;
 
+/**
+ * @public
+ */
 export type DocPathTemplate<Doc extends PathDoc> = PathTemplate<
   Extract<keyof Doc['paths'], string>
 >;
 
+/**
+ * @public
+ */
 export type DocPathMethod<
   Doc extends Pick<RequiredDoc, 'paths'>,
   Path extends DocPathTemplate<Doc>,
 > = keyof Doc['paths'][DocPath<Doc, Path>];
 
+/**
+ * @public
+ */
 export type MethodAwareDocPath<
   Doc extends PathDoc,
   Path extends PathTemplate<Extract<keyof Doc['paths'], string>>,
@@ -93,17 +121,26 @@ export type MethodAwareDocPath<
     : never;
 }>;
 
+/**
+ * @public
+ */
 export type DocOperation<
   Doc extends RequiredDoc,
   Path extends keyof Doc['paths'],
   Method extends keyof Doc['paths'][Path],
 > = Doc['paths'][Path][Method];
 
+/**
+ * @public
+ */
 export type ComponentTypes<Doc extends RequiredDoc> = Extract<
   keyof Doc['components'],
   string
 >;
 
+/**
+ * @public
+ */
 export type ComponentRef<
   Doc extends RequiredDoc,
   Type extends ComponentTypes<Doc>,
@@ -116,6 +153,9 @@ export type ComponentRef<
     : never
   : never;
 
+/**
+ * @public
+ */
 export type SchemaRef<Doc extends RequiredDoc, Schema> = Schema extends {
   $ref: `#/components/schemas/${infer Name}`;
 }
@@ -126,6 +166,9 @@ export type SchemaRef<Doc extends RequiredDoc, Schema> = Schema extends {
     : never
   : { [Key in keyof Schema]: SchemaRef<Doc, Schema[Key]> };
 
+/**
+ * @public
+ */
 export type ObjectWithContentSchema<
   Doc extends RequiredDoc,
   Object extends { content?: ContentObject },
@@ -134,30 +177,43 @@ export type ObjectWithContentSchema<
   : never;
 
 /**
- * From https://stackoverflow.com/questions/71393738/typescript-intersection-not-union-type-from-json-schema.
+ * From {@link https://stackoverflow.com/questions/71393738/typescript-intersection-not-union-type-from-json-schema}
  *
  * StackOverflow says not to do this, but union types aren't possible any other way.
+ * @public
  */
-
-type UnionToIntersection<U> = (U extends any ? (k: U) => void : never) extends (
-  k: infer I,
-) => void
+export type UnionToIntersection<U> = (
+  U extends any ? (k: U) => void : never
+) extends (k: infer I) => void
   ? I
   : never;
-type LastOf<T> = UnionToIntersection<
+
+/**
+ * @public
+ */
+export type LastOf<T> = UnionToIntersection<
   T extends any ? () => T : never
 > extends () => infer R
   ? R
   : never;
 
-type Push<T extends any[], V> = [...T, V];
+/**
+ * @public
+ */
+export type Push<T extends any[], V> = [...T, V];
 
+/**
+ * @public
+ */
 export type TuplifyUnion<
   T,
   L = LastOf<T>,
   N = [T] extends [never] ? true : false,
 > = true extends N ? [] : Push<TuplifyUnion<Exclude<T, L>>, L>;
 
+/**
+ * @public
+ */
 export type ConvertAll<T, R extends ReadonlyArray<unknown> = []> = T extends [
   infer First extends JSONSchema7,
   ...infer Rest,
@@ -165,6 +221,12 @@ export type ConvertAll<T, R extends ReadonlyArray<unknown> = []> = T extends [
   ? ConvertAll<Rest, [...R, FromSchema<First>]>
   : R;
 
-type UnknownIfNever<P> = [P] extends [never] ? unknown : P;
+/**
+ * @public
+ */
+export type UnknownIfNever<P> = [P] extends [never] ? unknown : P;
 
+/**
+ * @public
+ */
 export type ToTypeSafe<T> = UnknownIfNever<ConvertAll<TuplifyUnion<T>>[number]>;
diff --git a/plugins/openapi-router-common/src/types/express.ts b/plugins/openapi-router-common/src/types/express.ts
index dc7bf61832..4a6fcdedcb 100644
--- a/plugins/openapi-router-common/src/types/express.ts
+++ b/plugins/openapi-router-common/src/types/express.ts
@@ -16,12 +16,20 @@
 import core from 'express-serve-static-core';
 import { DocPathTemplate, MethodAwareDocPath, RequiredDoc } from './common';
 import { RequestBodyToJsonSchema } from './requests';
-import { ResponseBodyToJsonSchema } from './response';
+import { ResponseBodyToJsonSchema } from './responses';
 
-interface ParsedQs {
+/**
+ * Pulled from the express library.
+ * @public
+ */
+export interface ParsedQs {
   [key: string]: undefined | string | string[] | ParsedQs | ParsedQs[];
 }
 
+/**
+ * Typed express request handler.
+ * @public
+ */
 export type DocRequestHandler<
   Doc extends RequiredDoc,
   Path extends DocPathTemplate<Doc>,
@@ -34,6 +42,10 @@ export type DocRequestHandler<
   Record<string, string>
 >;
 
+/**
+ * Typed express error handler / request handler union type.
+ * @public
+ */
 export type DocRequestHandlerParams<
   Doc extends RequiredDoc,
   Path extends DocPathTemplate<Doc>,
@@ -46,8 +58,10 @@ export type DocRequestHandlerParams<
   Record<string, string>
 >;
 
-export type PathParams = string | RegExp | Array<string | RegExp>;
-
+/**
+ * Superset of the express router path matcher that enforces typed request and response bodies.
+ * @public
+ */
 export interface DocRequestMatcher<
   Doc extends RequiredDoc,
   T,
diff --git a/plugins/openapi-router-common/src/types/index.ts b/plugins/openapi-router-common/src/types/index.ts
index 8bd9fd0846..8862161ac0 100644
--- a/plugins/openapi-router-common/src/types/index.ts
+++ b/plugins/openapi-router-common/src/types/index.ts
@@ -14,4 +14,6 @@
  * limitations under the License.
  */
 export * from './common';
+export * from './express';
 export * from './requests';
+export * from './responses';
diff --git a/plugins/openapi-router-common/src/types/requests.ts b/plugins/openapi-router-common/src/types/requests.ts
index 6964f219a2..04c0a30f3a 100644
--- a/plugins/openapi-router-common/src/types/requests.ts
+++ b/plugins/openapi-router-common/src/types/requests.ts
@@ -32,7 +32,10 @@ import type {
   ToTypeSafe,
 } from './common';
 
-type RequestBody<
+/**
+ * @public
+ */
+export type RequestBody<
   Doc extends RequiredDoc,
   Path extends Extract<keyof Doc['paths'], string>,
   Method extends keyof Doc['paths'][Path],
@@ -46,6 +49,9 @@ type RequestBody<
     : never
   : DocOperation<Doc, Path, Method>['requestBody'];
 
+/**
+ * @public
+ */
 export type RequestBodySchema<
   Doc extends RequiredDoc,
   Path extends DocPathTemplate<Doc>,
@@ -54,6 +60,10 @@ export type RequestBodySchema<
   ? ObjectWithContentSchema<Doc, RequestBody<Doc, DocPath<Doc, Path>, Method>>
   : never;
 
+/**
+ * Transform the OpenAPI request body schema to a typesafe JSON schema.
+ * @public
+ */
 export type RequestBodyToJsonSchema<
   Doc extends RequiredDoc,
   Path extends PathTemplate<Extract<keyof Doc['paths'], string>>,
diff --git a/plugins/openapi-router-common/src/types/response.ts b/plugins/openapi-router-common/src/types/responses.ts
similarity index 92%
rename from plugins/openapi-router-common/src/types/response.ts
rename to plugins/openapi-router-common/src/types/responses.ts
index f20d94c2a9..50a8289dd6 100644
--- a/plugins/openapi-router-common/src/types/response.ts
+++ b/plugins/openapi-router-common/src/types/responses.ts
@@ -33,7 +33,10 @@ import type {
   ValueOf,
 } from './common';
 
-type Response<
+/**
+ * @public
+ */
+export type Response<
   Doc extends RequiredDoc,
   Path extends keyof Doc['paths'],
   Method extends keyof Doc['paths'][Path],
@@ -52,7 +55,10 @@ type Response<
     : never
   : DocOperation<Doc, Path, Method>['responses'][StatusCode];
 
-type Responses<
+/**
+ * @public
+ */
+export type Responses<
   Doc extends RequiredDoc,
   Path extends keyof Doc['paths'],
   Method extends keyof Doc['paths'][Path],
@@ -65,11 +71,17 @@ type Responses<
   >;
 };
 
+/**
+ * @public
+ */
 export type ResponseSchema<
   Doc extends RequiredDoc,
   Object extends ResponseObject,
 > = ObjectWithContentSchema<Doc, Object>;
 
+/**
+ * @public
+ */
 export type ResponseSchemas<
   Doc extends RequiredDoc,
   Path extends DocPathTemplate<Doc>,
@@ -87,6 +99,10 @@ export type ResponseSchemas<
     : never;
 };
 
+/**
+ * Transform the OpenAPI request body schema to a typesafe JSON schema.
+ * @public
+ */
 export type ResponseBodyToJsonSchema<
   Doc extends RequiredDoc,
   Path extends PathTemplate<Extract<keyof Doc['paths'], string>>,

From 57cd529ba93f576c67f1e9fab8dd0c28206bc9dc Mon Sep 17 00:00:00 2001
From: Aramis Sennyey <sennyeya@amazon.com>
Date: Wed, 22 Feb 2023 18:42:36 -0500
Subject: [PATCH 19/61] Update to use promise router, which doesn't throw.

Signed-off-by: Aramis Sennyey <sennyeya@amazon.com>
---
 plugins/catalog-backend/src/service/createRouter.ts | 3 ++-
 plugins/openapi-router-common/package.json          | 1 +
 plugins/openapi-router-common/src/example.ts        | 3 ++-
 plugins/openapi-router-common/src/index.ts          | 2 +-
 yarn.lock                                           | 1 +
 5 files changed, 7 insertions(+), 3 deletions(-)

diff --git a/plugins/catalog-backend/src/service/createRouter.ts b/plugins/catalog-backend/src/service/createRouter.ts
index 99e9c6b0df..9750272fae 100644
--- a/plugins/catalog-backend/src/service/createRouter.ts
+++ b/plugins/catalog-backend/src/service/createRouter.ts
@@ -24,7 +24,8 @@ import {
 } from '@backstage/catalog-model';
 import { Config } from '@backstage/config';
 import { NotFoundError, serializeError } from '@backstage/errors';
-import express, { Router } from 'express';
+import express from 'express';
+import Router from 'express-promise-router';
 import { Logger } from 'winston';
 import yn from 'yn';
 import { z } from 'zod';
diff --git a/plugins/openapi-router-common/package.json b/plugins/openapi-router-common/package.json
index c121084abc..9607f39bfa 100644
--- a/plugins/openapi-router-common/package.json
+++ b/plugins/openapi-router-common/package.json
@@ -32,6 +32,7 @@
   "dependencies": {
     "@backstage/backend-common": "workspace:^",
     "express": "^4.17.1",
+    "express-promise-router": "^4.1.0",
     "json-schema-to-ts": "^2.6.2",
     "openapi-types": "^12.1.0",
     "openapi3-ts": "^3.1.2",
diff --git a/plugins/openapi-router-common/src/example.ts b/plugins/openapi-router-common/src/example.ts
index f89fe17e3f..798e5ea3b8 100644
--- a/plugins/openapi-router-common/src/example.ts
+++ b/plugins/openapi-router-common/src/example.ts
@@ -13,7 +13,8 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-import express, { Router } from 'express';
+import express from 'express';
+import Router from 'express-promise-router';
 import { ApiRouter, DeepWriteable } from './router';
 import doc from './schema/petstore';
 
diff --git a/plugins/openapi-router-common/src/index.ts b/plugins/openapi-router-common/src/index.ts
index 3aab4ab1d1..8ca7bd3c5b 100644
--- a/plugins/openapi-router-common/src/index.ts
+++ b/plugins/openapi-router-common/src/index.ts
@@ -20,5 +20,5 @@
  * @packageDocumentation
  */
 
-export type { ApiRouter } from './router';
+export type { ApiRouter, DeepWriteable } from './router';
 export * from './types';
diff --git a/yarn.lock b/yarn.lock
index 5d2931cc57..8c689e4ae9 100644
--- a/yarn.lock
+++ b/yarn.lock
@@ -7801,6 +7801,7 @@ __metadata:
     "@backstage/backend-common": "workspace:^"
     "@backstage/cli": "workspace:^"
     express: ^4.17.1
+    express-promise-router: ^4.1.0
     json-schema-to-ts: ^2.6.2
     openapi-types: ^12.1.0
     openapi3-ts: ^3.1.2

From bdb063712c90e496f9cc8f4e82010945c1c32f9c Mon Sep 17 00:00:00 2001
From: Aramis Sennyey <sennyeya@amazon.com>
Date: Wed, 22 Feb 2023 18:53:22 -0500
Subject: [PATCH 20/61] Update API report.

Signed-off-by: Aramis Sennyey <sennyeya@amazon.com>
---
 plugins/openapi-router-common/api-report.md | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/plugins/openapi-router-common/api-report.md b/plugins/openapi-router-common/api-report.md
index 6dbe59dc06..de82f1e5c7 100644
--- a/plugins/openapi-router-common/api-report.md
+++ b/plugins/openapi-router-common/api-report.md
@@ -62,6 +62,11 @@ export type ConvertAll<T, R extends ReadonlyArray<unknown> = []> = T extends [
   ? ConvertAll<Rest, [...R, FromSchema<First>]>
   : R;
 
+// @public
+export type DeepWriteable<T> = {
+  -readonly [P in keyof T]: DeepWriteable<T[P]>;
+};
+
 // @public (undocumented)
 export type DocOperation<
   Doc extends RequiredDoc,

From 3d2073402d6c8fb7b56021cf76731807167a838b Mon Sep 17 00:00:00 2001
From: Aramis Sennyey <sennyeya@amazon.com>
Date: Wed, 22 Feb 2023 19:08:56 -0500
Subject: [PATCH 21/61] Fix type dependencies.

Signed-off-by: Aramis Sennyey <sennyeya@amazon.com>
---
 plugins/openapi-router-common/package.json |  4 +-
 yarn.lock                                  | 48 ++++++++++++++++++++++
 2 files changed, 51 insertions(+), 1 deletion(-)

diff --git a/plugins/openapi-router-common/package.json b/plugins/openapi-router-common/package.json
index 9607f39bfa..c1af958026 100644
--- a/plugins/openapi-router-common/package.json
+++ b/plugins/openapi-router-common/package.json
@@ -24,7 +24,9 @@
     "postpack": "backstage-cli package postpack"
   },
   "devDependencies": {
-    "@backstage/cli": "workspace:^"
+    "@backstage/cli": "workspace:^",
+    "@types/express": "^4.17.17",
+    "@types/express-serve-static-core": "^4.17.33"
   },
   "files": [
     "dist"
diff --git a/yarn.lock b/yarn.lock
index 8c689e4ae9..d31015c608 100644
--- a/yarn.lock
+++ b/yarn.lock
@@ -7800,6 +7800,8 @@ __metadata:
   dependencies:
     "@backstage/backend-common": "workspace:^"
     "@backstage/cli": "workspace:^"
+    "@types/express": ^4.17.17
+    "@types/express-serve-static-core": ^4.17.33
     express: ^4.17.1
     express-promise-router: ^4.1.0
     json-schema-to-ts: ^2.6.2
@@ -15908,6 +15910,28 @@ __metadata:
   languageName: node
   linkType: hard
 
+"@types/express-serve-static-core@npm:*, @types/express-serve-static-core@npm:^4.17.18, @types/express-serve-static-core@npm:^4.17.31, @types/express-serve-static-core@npm:^4.17.33, @types/express-serve-static-core@npm:^4.17.5":
+  version: 4.17.33
+  resolution: "@types/express-serve-static-core@npm:4.17.33"
+  dependencies:
+    "@types/node": "*"
+    "@types/qs": "*"
+    "@types/range-parser": "*"
+  checksum: dce580d16b85f207445af9d4053d66942b27d0c72e86153089fa00feee3e96ae336b7bedb31ed4eea9e553c99d6dd356ed6e0928f135375d9f862a1a8015adf2
+  languageName: node
+  linkType: hard
+
+"@types/express-serve-static-core@npm:*, @types/express-serve-static-core@npm:^4.17.30, @types/express-serve-static-core@npm:^4.17.31, @types/express-serve-static-core@npm:^4.17.5":
+  version: 4.17.33
+  resolution: "@types/express-serve-static-core@npm:4.17.33"
+  dependencies:
+    "@types/node": "*"
+    "@types/qs": "*"
+    "@types/range-parser": "*"
+  checksum: dce580d16b85f207445af9d4053d66942b27d0c72e86153089fa00feee3e96ae336b7bedb31ed4eea9e553c99d6dd356ed6e0928f135375d9f862a1a8015adf2
+  languageName: node
+  linkType: hard
+
 "@types/express-serve-static-core@npm:*, @types/express-serve-static-core@npm:^4.17.30, @types/express-serve-static-core@npm:^4.17.33, @types/express-serve-static-core@npm:^4.17.5":
   version: 4.17.33
   resolution: "@types/express-serve-static-core@npm:4.17.33"
@@ -15950,6 +15974,30 @@ __metadata:
   languageName: node
   linkType: hard
 
+"@types/express@npm:4.17.14":
+  version: 4.17.14
+  resolution: "@types/express@npm:4.17.14"
+  dependencies:
+    "@types/body-parser": "*"
+    "@types/express-serve-static-core": ^4.17.18
+    "@types/qs": "*"
+    "@types/serve-static": "*"
+  checksum: 15c1af46d02de834e4a225eccaa9d85c0370fdbb3ed4e1bc2d323d24872309961542b993ae236335aeb3e278630224a6ea002078d39e651d78a3b0356b1eaa79
+  languageName: node
+  linkType: hard
+
+"@types/express@npm:^4.17.17":
+  version: 4.17.17
+  resolution: "@types/express@npm:4.17.17"
+  dependencies:
+    "@types/body-parser": "*"
+    "@types/express-serve-static-core": ^4.17.33
+    "@types/qs": "*"
+    "@types/serve-static": "*"
+  checksum: 0196dacc275ac3ce89d7364885cb08e7fb61f53ca101f65886dbf1daf9b7eb05c0943e2e4bbd01b0cc5e50f37e0eea7e4cbe97d0304094411ac73e1b7998f4da
+  languageName: node
+  linkType: hard
+
 "@types/fs-extra@npm:^9.0.1, @types/fs-extra@npm:^9.0.3, @types/fs-extra@npm:^9.0.5, @types/fs-extra@npm:^9.0.6":
   version: 9.0.13
   resolution: "@types/fs-extra@npm:9.0.13"

From 3973f3e7af73e6c9736552c843c7d0d6218f1155 Mon Sep 17 00:00:00 2001
From: Aramis Sennyey <sennyeya@amazon.com>
Date: Wed, 22 Feb 2023 19:55:06 -0500
Subject: [PATCH 22/61] Another dedupe fix...

Signed-off-by: Aramis Sennyey <sennyeya@amazon.com>
---
 plugins/openapi-router-common/package.json |  2 +-
 yarn.lock                                  | 16 ++--------------
 2 files changed, 3 insertions(+), 15 deletions(-)

diff --git a/plugins/openapi-router-common/package.json b/plugins/openapi-router-common/package.json
index c1af958026..536bf7261b 100644
--- a/plugins/openapi-router-common/package.json
+++ b/plugins/openapi-router-common/package.json
@@ -25,7 +25,7 @@
   },
   "devDependencies": {
     "@backstage/cli": "workspace:^",
-    "@types/express": "^4.17.17",
+    "@types/express": "^4.17.6",
     "@types/express-serve-static-core": "^4.17.33"
   },
   "files": [
diff --git a/yarn.lock b/yarn.lock
index d31015c608..91df44aac6 100644
--- a/yarn.lock
+++ b/yarn.lock
@@ -7800,7 +7800,7 @@ __metadata:
   dependencies:
     "@backstage/backend-common": "workspace:^"
     "@backstage/cli": "workspace:^"
-    "@types/express": ^4.17.17
+    "@types/express": ^4.17.6
     "@types/express-serve-static-core": ^4.17.33
     express: ^4.17.1
     express-promise-router: ^4.1.0
@@ -15910,7 +15910,7 @@ __metadata:
   languageName: node
   linkType: hard
 
-"@types/express-serve-static-core@npm:*, @types/express-serve-static-core@npm:^4.17.18, @types/express-serve-static-core@npm:^4.17.31, @types/express-serve-static-core@npm:^4.17.33, @types/express-serve-static-core@npm:^4.17.5":
+"@types/express-serve-static-core@npm:*, @types/express-serve-static-core@npm:^4.17.18, @types/express-serve-static-core@npm:^4.17.33, @types/express-serve-static-core@npm:^4.17.5":
   version: 4.17.33
   resolution: "@types/express-serve-static-core@npm:4.17.33"
   dependencies:
@@ -15986,18 +15986,6 @@ __metadata:
   languageName: node
   linkType: hard
 
-"@types/express@npm:^4.17.17":
-  version: 4.17.17
-  resolution: "@types/express@npm:4.17.17"
-  dependencies:
-    "@types/body-parser": "*"
-    "@types/express-serve-static-core": ^4.17.33
-    "@types/qs": "*"
-    "@types/serve-static": "*"
-  checksum: 0196dacc275ac3ce89d7364885cb08e7fb61f53ca101f65886dbf1daf9b7eb05c0943e2e4bbd01b0cc5e50f37e0eea7e4cbe97d0304094411ac73e1b7998f4da
-  languageName: node
-  linkType: hard
-
 "@types/fs-extra@npm:^9.0.1, @types/fs-extra@npm:^9.0.3, @types/fs-extra@npm:^9.0.5, @types/fs-extra@npm:^9.0.6":
   version: 9.0.13
   resolution: "@types/fs-extra@npm:9.0.13"

From c41c5569524163a86f30a01a5668354a411407cd Mon Sep 17 00:00:00 2001
From: Aramis Sennyey <sennyeya@amazon.com>
Date: Thu, 23 Feb 2023 09:36:52 -0500
Subject: [PATCH 23/61] Switch to regular dependency.

Signed-off-by: Aramis Sennyey <sennyeya@amazon.com>
---
 plugins/openapi-router-common/package.json | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/plugins/openapi-router-common/package.json b/plugins/openapi-router-common/package.json
index 536bf7261b..695a7bfc4d 100644
--- a/plugins/openapi-router-common/package.json
+++ b/plugins/openapi-router-common/package.json
@@ -24,15 +24,15 @@
     "postpack": "backstage-cli package postpack"
   },
   "devDependencies": {
-    "@backstage/cli": "workspace:^",
-    "@types/express": "^4.17.6",
-    "@types/express-serve-static-core": "^4.17.33"
+    "@backstage/cli": "workspace:^"
   },
   "files": [
     "dist"
   ],
   "dependencies": {
     "@backstage/backend-common": "workspace:^",
+    "@types/express": "^4.17.6",
+    "@types/express-serve-static-core": "^4.17.33",
     "express": "^4.17.1",
     "express-promise-router": "^4.1.0",
     "json-schema-to-ts": "^2.6.2",

From 6643f4fa6815f48a1d8815b186d1153dd591b0f5 Mon Sep 17 00:00:00 2001
From: Aramis Sennyey <sennyeya@amazon.com>
Date: Tue, 28 Feb 2023 13:19:39 -0500
Subject: [PATCH 24/61] Add parameters for the paginated query response and fix
 cursor description.

Signed-off-by: Aramis Sennyey <sennyeya@amazon.com>
---
 plugins/catalog-backend/openapi.yaml | 78 +++++++++++++++++++++++-----
 1 file changed, 65 insertions(+), 13 deletions(-)

diff --git a/plugins/catalog-backend/openapi.yaml b/plugins/catalog-backend/openapi.yaml
index c53a6443ba..9eb1fdd87c 100644
--- a/plugins/catalog-backend/openapi.yaml
+++ b/plugins/catalog-backend/openapi.yaml
@@ -15,7 +15,44 @@ servers:
 components:
   examples: {}
   headers: {}
-  parameters: {}
+  parameters:
+    cursor:
+      name: cursor
+      in: query
+      description: Cursor to a set page of results.
+      required: false
+      schema:
+        type: string
+    fields:
+      name: fields
+      in: query
+      description: Restrict to just these fields in the response.
+      required: false
+      schema:
+        type: string
+    limit:
+      name: limit
+      in: query
+      description: Number of records to return in the response.
+      required: false
+      schema:
+        type: integer
+        minimum: 1
+    sortField:
+      name: sortField
+      in: query
+      description: The fields to sort returned results by.
+      required: false
+      schema:
+        type: array
+        items:
+          type: array
+          items:
+            type: string
+          description: A two-item tuple of [field, order].
+
+      explode: true
+      style: form
   requestBodies: {}
   responses: {}
   schemas:
@@ -211,17 +248,16 @@ components:
         count:
           type: number
       additionalProperties: false
-    EntityFacets:
-      type: array
-      items:
-        $ref: '#/components/schemas/EntityFacet'
+
     EntityFacetsResponse:
       type: object
       properties:
         facets:
           type: object
           additionalProperties:
-            $ref: '#/components/schemas/EntityFacets'
+            type: array
+            items:
+              $ref: '#/components/schemas/EntityFacet'
       required:
         - facets
       additionalProperties: false
@@ -363,7 +399,7 @@ components:
                 that do so in such a way that it breaks semantics.
           description: Metadata fields common to all versions/kinds of entity.
       additionalProperties: false
-    RecursivePartial_Entity_:
+    RecursivePartialEntity:
       type: object
       properties:
         apiVersion:
@@ -392,7 +428,7 @@ components:
           type: string
           description: |-
             A text to show to the user to inform about the choices made. Like, it could say
-            "Found a CODEOWNERS file that covers this target, so we suggest leaving this 
+            "Found a CODEOWNERS file that covers this target, so we suggest leaving this
             field empty; which would currently make it owned by X" where X is taken from the
             codeowners file.
         value:
@@ -424,7 +460,7 @@ components:
           items:
             $ref: '#/components/schemas/AnalyzeLocationEntityField'
         entity:
-          $ref: '#/components/schemas/RecursivePartial_Entity_'
+          $ref: '#/components/schemas/RecursivePartialEntity'
       required:
         - fields
         - entity
@@ -506,11 +542,11 @@ components:
             nextCursor:
               type: string
               description: |-
-                Base64 encoded database query for the next page.
+                The cursor for the next batch of entities.
             prevCursor:
               type: string
               description: |-
-                Base64 encoded database query for the previous page.
+                The cursor for the previous batch of entities.
       additionalProperties: false
   securitySchemes:
     JWT:
@@ -717,11 +753,27 @@ paths:
         - {}
         - JWT: []
       parameters:
-        - in: query
-          name: fields
+        - $ref: '#/components/parameters/fields'
+        - $ref: '#/components/parameters/limit'
+        - $ref: '#/components/parameters/sortField'
+        - $ref: '#/components/parameters/cursor'
+        - name: fullTextFilterTerm
+          in: query
+          description: Text search term.
           required: false
           schema:
             type: string
+        - name: fullTextFilterFields
+          in: query
+          description: A comma separated list of fields to sort returned results by.
+          required: false
+          schema:
+            type: array
+            items:
+              type: string
+          explode: false
+          style: form
+
       requestBody:
         required: true
         content:

From 68c4160011a0132b7d4e19ea8b7bfd0f73b32475 Mon Sep 17 00:00:00 2001
From: Aramis Sennyey <sennyeya@amazon.com>
Date: Tue, 28 Feb 2023 13:57:35 -0500
Subject: [PATCH 25/61] Remove use of DeepWriteable. Support `as const` fully.

Signed-off-by: Aramis Sennyey <sennyeya@amazon.com>
---
 plugins/catalog-backend/openapi.yaml          |    1 -
 .../src/service/createRouter.ts               |    4 +-
 .../src/service/schema/openapi.ts             |  102 +-
 plugins/openapi-router-common/src/example.ts  |    4 +-
 plugins/openapi-router-common/src/index.ts    |    2 +-
 plugins/openapi-router-common/src/router.ts   |    4 +-
 .../src/schema/openapi.ts                     | 1263 -----------------
 .../openapi-router-common/src/types/common.ts |    6 +-
 .../src/types/immutable.ts                    |   51 +
 .../src/types/requests.ts                     |    2 +-
 10 files changed, 146 insertions(+), 1293 deletions(-)
 delete mode 100644 plugins/openapi-router-common/src/schema/openapi.ts
 create mode 100644 plugins/openapi-router-common/src/types/immutable.ts

diff --git a/plugins/catalog-backend/openapi.yaml b/plugins/catalog-backend/openapi.yaml
index 9eb1fdd87c..5028f4d556 100644
--- a/plugins/catalog-backend/openapi.yaml
+++ b/plugins/catalog-backend/openapi.yaml
@@ -328,7 +328,6 @@ components:
         - $ref: '#/components/schemas/JsonObject'
         - type: object
           properties:
-            properties:
             links:
               type: array
               items:
diff --git a/plugins/catalog-backend/src/service/createRouter.ts b/plugins/catalog-backend/src/service/createRouter.ts
index 9750272fae..2f83723281 100644
--- a/plugins/catalog-backend/src/service/createRouter.ts
+++ b/plugins/catalog-backend/src/service/createRouter.ts
@@ -50,7 +50,7 @@ import {
   locationInput,
   validateRequestBody,
 } from './util';
-import { ApiRouter, DeepWriteable } from '@backstage/plugin-openapi-router';
+import { ApiRouter } from '@backstage/plugin-openapi-router';
 import spec from './schema/openapi';
 
 /**
@@ -87,7 +87,7 @@ export async function createRouter(
     logger,
     permissionIntegrationRouter,
   } = options;
-  const router = Router() as ApiRouter<DeepWriteable<typeof spec>>;
+  const router = Router() as ApiRouter<typeof spec>;
   router.use(express.json());
 
   const readonlyEnabled =
diff --git a/plugins/catalog-backend/src/service/schema/openapi.ts b/plugins/catalog-backend/src/service/schema/openapi.ts
index 8d011ad7a4..ce725a59de 100644
--- a/plugins/catalog-backend/src/service/schema/openapi.ts
+++ b/plugins/catalog-backend/src/service/schema/openapi.ts
@@ -34,7 +34,54 @@ export default {
   components: {
     examples: {},
     headers: {},
-    parameters: {},
+    parameters: {
+      cursor: {
+        name: 'cursor',
+        in: 'query',
+        description: 'Cursor to a set page of results.',
+        required: false,
+        schema: {
+          type: 'string',
+        },
+      },
+      fields: {
+        name: 'fields',
+        in: 'query',
+        description: 'Restrict to just these fields in the response.',
+        required: false,
+        schema: {
+          type: 'string',
+        },
+      },
+      limit: {
+        name: 'limit',
+        in: 'query',
+        description: 'Number of records to return in the response.',
+        required: false,
+        schema: {
+          type: 'integer',
+          minimum: 1,
+        },
+      },
+      sortField: {
+        name: 'sortField',
+        in: 'query',
+        description: 'The fields to sort returned results by.',
+        required: false,
+        schema: {
+          type: 'array',
+          items: {
+            type: 'array',
+            items: {
+              type: 'string',
+            },
+            description: 'A two-item tuple of [field, order].',
+          },
+        },
+        explode: true,
+        style: 'form',
+      },
+    },
     requestBodies: {},
     responses: {},
     schemas: {
@@ -253,19 +300,16 @@ export default {
         },
         additionalProperties: false,
       },
-      EntityFacets: {
-        type: 'array',
-        items: {
-          $ref: '#/components/schemas/EntityFacet',
-        },
-      },
       EntityFacetsResponse: {
         type: 'object',
         properties: {
           facets: {
             type: 'object',
             additionalProperties: {
-              $ref: '#/components/schemas/EntityFacets',
+              type: 'array',
+              items: {
+                $ref: '#/components/schemas/EntityFacet',
+              },
             },
           },
         },
@@ -349,7 +393,6 @@ export default {
           {
             type: 'object',
             properties: {
-              properties: null,
               links: {
                 type: 'array',
                 items: {
@@ -408,7 +451,7 @@ export default {
         ],
         additionalProperties: false,
       },
-      RecursivePartial_Entity_: {
+      RecursivePartialEntity: {
         type: 'object',
         properties: {
           apiVersion: {
@@ -444,7 +487,7 @@ export default {
           description: {
             type: 'string',
             description:
-              'A text to show to the user to inform about the choices made. Like, it could say\n"Found a CODEOWNERS file that covers this target, so we suggest leaving this \nfield empty; which would currently make it owned by X" where X is taken from the\ncodeowners file.',
+              'A text to show to the user to inform about the choices made. Like, it could say\n"Found a CODEOWNERS file that covers this target, so we suggest leaving this\nfield empty; which would currently make it owned by X" where X is taken from the\ncodeowners file.',
           },
           value: {
             type: 'string',
@@ -479,7 +522,7 @@ export default {
             },
           },
           entity: {
-            $ref: '#/components/schemas/RecursivePartial_Entity_',
+            $ref: '#/components/schemas/RecursivePartialEntity',
           },
         },
         required: ['fields', 'entity'],
@@ -573,12 +616,11 @@ export default {
             properties: {
               nextCursor: {
                 type: 'string',
-                description: 'Base64 encoded database query for the next page.',
+                description: 'The cursor for the next batch of entities.',
               },
               prevCursor: {
                 type: 'string',
-                description:
-                  'Base64 encoded database query for the previous page.',
+                description: 'The cursor for the previous batch of entities.',
               },
             },
           },
@@ -928,13 +970,41 @@ export default {
         ],
         parameters: [
           {
+            $ref: '#/components/parameters/fields',
+          },
+          {
+            $ref: '#/components/parameters/limit',
+          },
+          {
+            $ref: '#/components/parameters/sortField',
+          },
+          {
+            $ref: '#/components/parameters/cursor',
+          },
+          {
+            name: 'fullTextFilterTerm',
             in: 'query',
-            name: 'fields',
+            description: 'Text search term.',
             required: false,
             schema: {
               type: 'string',
             },
           },
+          {
+            name: 'fullTextFilterFields',
+            in: 'query',
+            description:
+              'A comma separated list of fields to sort returned results by.',
+            required: false,
+            schema: {
+              type: 'array',
+              items: {
+                type: 'string',
+              },
+            },
+            explode: false,
+            style: 'form',
+          },
         ],
         requestBody: {
           required: true,
diff --git a/plugins/openapi-router-common/src/example.ts b/plugins/openapi-router-common/src/example.ts
index 798e5ea3b8..af9871993a 100644
--- a/plugins/openapi-router-common/src/example.ts
+++ b/plugins/openapi-router-common/src/example.ts
@@ -15,7 +15,7 @@
  */
 import express from 'express';
 import Router from 'express-promise-router';
-import { ApiRouter, DeepWriteable } from './router';
+import { ApiRouter } from './router';
 import doc from './schema/petstore';
 
 interface RouterOptions {}
@@ -24,7 +24,7 @@ export async function createRouter(
   options: RouterOptions,
 ): Promise<express.Router> {
   console.log(options);
-  const router = Router() as ApiRouter<DeepWriteable<typeof doc>>;
+  const router = Router() as ApiRouter<typeof doc>;
 
   router.get('/pets/:uid', (_, res) => {
     res.json({
diff --git a/plugins/openapi-router-common/src/index.ts b/plugins/openapi-router-common/src/index.ts
index 8ca7bd3c5b..3aab4ab1d1 100644
--- a/plugins/openapi-router-common/src/index.ts
+++ b/plugins/openapi-router-common/src/index.ts
@@ -20,5 +20,5 @@
  * @packageDocumentation
  */
 
-export type { ApiRouter, DeepWriteable } from './router';
+export type { ApiRouter } from './router';
 export * from './types';
diff --git a/plugins/openapi-router-common/src/router.ts b/plugins/openapi-router-common/src/router.ts
index 417ffb157f..3d46f7ce6f 100644
--- a/plugins/openapi-router-common/src/router.ts
+++ b/plugins/openapi-router-common/src/router.ts
@@ -20,8 +20,8 @@ import { RequiredDoc, DocRequestMatcher } from './types';
  * Helper to transform readonly `as const` API specs for the ApiRouter.
  * @public
  */
-export type DeepWriteable<T> = {
-  -readonly [P in keyof T]: DeepWriteable<T[P]>;
+export type DeepReadonly<T> = {
+  readonly [P in keyof T]: DeepReadonly<T[P]>;
 };
 
 /**
diff --git a/plugins/openapi-router-common/src/schema/openapi.ts b/plugins/openapi-router-common/src/schema/openapi.ts
deleted file mode 100644
index 8d011ad7a4..0000000000
--- a/plugins/openapi-router-common/src/schema/openapi.ts
+++ /dev/null
@@ -1,1263 +0,0 @@
-/*
- * Copyright 2023 The Backstage Authors
- *
- * Licensed under the Apache License, Version 2.0 (the "License");
- * you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- *     http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
- */
-export default {
-  openapi: '3.1.0',
-  info: {
-    title: '@backstage/plugin-catalog-backend',
-    version: '1',
-    description:
-      'The Backstage backend plugin that provides the Backstage catalog',
-    license: {
-      name: 'Apache-2.0',
-      url: 'http://www.apache.org/licenses/LICENSE-2.0.html',
-    },
-    contact: {},
-  },
-  servers: [
-    {
-      url: '/',
-    },
-  ],
-  components: {
-    examples: {},
-    headers: {},
-    parameters: {},
-    requestBodies: {},
-    responses: {},
-    schemas: {
-      JsonObject: {
-        type: 'object',
-        properties: {},
-        description: 'A type representing all allowed JSON object values.',
-      },
-      MapStringString: {
-        type: 'object',
-        properties: {},
-        additionalProperties: {
-          type: 'string',
-        },
-        description: 'Construct a type with a set of properties K of type T',
-      },
-      EntityLink: {
-        type: 'object',
-        properties: {
-          type: {
-            type: 'string',
-            description:
-              'An optional value to categorize links into specific groups',
-          },
-          icon: {
-            type: 'string',
-            description:
-              'An optional semantic key that represents a visual icon.',
-          },
-          title: {
-            type: 'string',
-            description: 'An optional descriptive title for the link.',
-          },
-          url: {
-            type: 'string',
-            description: 'The url to the external site, document, etc.',
-          },
-        },
-        required: ['url'],
-        description:
-          'A link to external information that is related to the entity.',
-        additionalProperties: false,
-      },
-      EntityMeta: {
-        allOf: [
-          {
-            $ref: '#/components/schemas/JsonObject',
-          },
-          {
-            type: 'object',
-            properties: {
-              links: {
-                type: 'array',
-                items: {
-                  $ref: '#/components/schemas/EntityLink',
-                },
-                description:
-                  'A list of external hyperlinks related to the entity.',
-              },
-              tags: {
-                type: 'array',
-                items: {
-                  type: 'string',
-                },
-                description:
-                  'A list of single-valued strings, to for example classify catalog entities in\nvarious ways.',
-              },
-              annotations: {
-                $ref: '#/components/schemas/MapStringString',
-              },
-              labels: {
-                $ref: '#/components/schemas/MapStringString',
-              },
-              description: {
-                type: 'string',
-                description:
-                  'A short (typically relatively few words, on one line) description of the\nentity.',
-              },
-              title: {
-                type: 'string',
-                description:
-                  'A display name of the entity, to be presented in user interfaces instead\nof the `name` property above, when available.\nThis field is sometimes useful when the `name` is cumbersome or ends up\nbeing perceived as overly technical. The title generally does not have\nas stringent format requirements on it, so it may contain special\ncharacters and be more explanatory. Do keep it very short though, and\navoid situations where a title can be confused with the name of another\nentity, or where two entities share a title.\nNote that this is only for display purposes, and may be ignored by some\nparts of the code. Entity references still always make use of the `name`\nproperty, not the title.',
-              },
-              namespace: {
-                type: 'string',
-                description: 'The namespace that the entity belongs to.',
-              },
-              name: {
-                type: 'string',
-                description:
-                  'The name of the entity.\nMust be unique within the catalog at any given point in time, for any\ngiven namespace + kind pair. This value is part of the technical\nidentifier of the entity, and as such it will appear in URLs, database\ntables, entity references, and similar. It is subject to restrictions\nregarding what characters are allowed.\nIf you want to use a different, more human readable string with fewer\nrestrictions on it in user interfaces, see the `title` field below.',
-              },
-              etag: {
-                type: 'string',
-                description:
-                  'An opaque string that changes for each update operation to any part of\nthe entity, including metadata.\nThis field can not be set by the user at creation time, and the server\nwill reject an attempt to do so. The field will be populated in read\noperations. The field can (optionally) be specified when performing\nupdate or delete operations, and the server will then reject the\noperation if it does not match the current stored value.',
-              },
-              uid: {
-                type: 'string',
-                description:
-                  'A globally unique ID for the entity.\nThis field can not be set by the user at creation time, and the server\nwill reject an attempt to do so. The field will be populated in read\noperations. The field can (optionally) be specified when performing\nupdate or delete operations, but the server is free to reject requests\nthat do so in such a way that it breaks semantics.',
-              },
-            },
-            required: ['name'],
-          },
-        ],
-        description: 'Metadata fields common to all versions/kinds of entity.',
-        additionalProperties: false,
-      },
-      EntityRelation: {
-        type: 'object',
-        properties: {
-          targetRef: {
-            type: 'string',
-            description: 'The entity ref of the target of this relation.',
-          },
-          type: {
-            type: 'string',
-            description: 'The type of the relation.',
-          },
-        },
-        required: ['targetRef', 'type'],
-        description:
-          'A relation of a specific type to another entity in the catalog.',
-        additionalProperties: false,
-      },
-      Entity: {
-        type: 'object',
-        properties: {
-          relations: {
-            type: 'array',
-            items: {
-              $ref: '#/components/schemas/EntityRelation',
-            },
-            description:
-              'The relations that this entity has with other entities.',
-          },
-          spec: {
-            $ref: '#/components/schemas/JsonObject',
-          },
-          metadata: {
-            $ref: '#/components/schemas/EntityMeta',
-          },
-          kind: {
-            type: 'string',
-            description: 'The high level entity type being described.',
-          },
-          apiVersion: {
-            type: 'string',
-            description:
-              'The version of specification format for this particular entity that\nthis is written against.',
-          },
-        },
-        required: ['metadata', 'kind', 'apiVersion'],
-        description:
-          "The parts of the format that's common to all versions/kinds of entity.",
-        additionalProperties: false,
-      },
-      EntityAncestryResponse: {
-        type: 'object',
-        properties: {
-          items: {
-            type: 'array',
-            items: {
-              type: 'object',
-              properties: {
-                parentEntityRefs: {
-                  items: {
-                    type: 'string',
-                  },
-                  type: 'array',
-                },
-                entity: {
-                  $ref: '#/components/schemas/Entity',
-                },
-              },
-              required: ['parentEntityRefs', 'entity'],
-            },
-          },
-          rootEntityRef: {
-            type: 'string',
-          },
-        },
-        required: ['items', 'rootEntityRef'],
-        additionalProperties: false,
-      },
-      EntitiesBatchResponse: {
-        type: 'object',
-        properties: {
-          items: {
-            type: 'array',
-            items: {
-              allOf: [
-                {
-                  $ref: '#/components/schemas/Entity',
-                },
-              ],
-              nullable: true,
-            },
-            description:
-              'The list of entities, in the same order as the refs in the request. Entries\nthat are null signify that no entity existed with that ref.',
-          },
-        },
-        required: ['items'],
-        additionalProperties: false,
-      },
-      EntityFacet: {
-        type: 'object',
-        properties: {
-          value: {
-            type: 'string',
-          },
-          count: {
-            type: 'number',
-          },
-        },
-        additionalProperties: false,
-      },
-      EntityFacets: {
-        type: 'array',
-        items: {
-          $ref: '#/components/schemas/EntityFacet',
-        },
-      },
-      EntityFacetsResponse: {
-        type: 'object',
-        properties: {
-          facets: {
-            type: 'object',
-            additionalProperties: {
-              $ref: '#/components/schemas/EntityFacets',
-            },
-          },
-        },
-        required: ['facets'],
-        additionalProperties: false,
-      },
-      Location: {
-        type: 'object',
-        properties: {
-          target: {
-            type: 'string',
-          },
-          type: {
-            type: 'string',
-          },
-          id: {
-            type: 'string',
-          },
-        },
-        required: ['target', 'type', 'id'],
-        description: 'Entity location for a specific entity.',
-        additionalProperties: false,
-      },
-      LocationSpec: {
-        type: 'object',
-        properties: {
-          presence: {
-            type: 'string',
-            enum: ['optional', 'required'],
-          },
-          target: {
-            type: 'string',
-          },
-          type: {
-            type: 'string',
-          },
-        },
-        required: ['target', 'type'],
-        description: 'Holds the entity location information.',
-        additionalProperties: false,
-      },
-      AnalyzeLocationExistingEntity: {
-        type: 'object',
-        properties: {
-          entity: {
-            $ref: '#/components/schemas/Entity',
-          },
-          isRegistered: {
-            type: 'boolean',
-          },
-          location: {
-            $ref: '#/components/schemas/LocationSpec',
-          },
-        },
-        required: ['entity', 'isRegistered', 'location'],
-        description:
-          "If the folder pointed to already contained catalog info yaml files, they are\nread and emitted like this so that the frontend can inform the user that it\nlocated them and can make sure to register them as well if they weren't\nalready",
-        additionalProperties: false,
-      },
-      RecursivePartialEntityRelation: {
-        type: 'object',
-        properties: {
-          targetRef: {
-            type: 'string',
-            description: 'The entity ref of the target of this relation.',
-          },
-          type: {
-            type: 'string',
-            description: 'The type of the relation.',
-          },
-        },
-        description:
-          'A relation of a specific type to another entity in the catalog.',
-        additionalProperties: false,
-      },
-      RecursivePartialEntityMeta: {
-        allOf: [
-          {
-            $ref: '#/components/schemas/JsonObject',
-          },
-          {
-            type: 'object',
-            properties: {
-              properties: null,
-              links: {
-                type: 'array',
-                items: {
-                  $ref: '#/components/schemas/EntityLink',
-                },
-                description:
-                  'A list of external hyperlinks related to the entity.',
-              },
-              tags: {
-                type: 'array',
-                items: {
-                  type: 'string',
-                },
-                description:
-                  'A list of single-valued strings, to for example classify catalog entities in\nvarious ways.',
-              },
-              annotations: {
-                $ref: '#/components/schemas/MapStringString',
-              },
-              labels: {
-                $ref: '#/components/schemas/MapStringString',
-              },
-              description: {
-                type: 'string',
-                description:
-                  'A short (typically relatively few words, on one line) description of the\nentity.',
-              },
-              title: {
-                type: 'string',
-                description:
-                  'A display name of the entity, to be presented in user interfaces instead\nof the `name` property above, when available.\nThis field is sometimes useful when the `name` is cumbersome or ends up\nbeing perceived as overly technical. The title generally does not have\nas stringent format requirements on it, so it may contain special\ncharacters and be more explanatory. Do keep it very short though, and\navoid situations where a title can be confused with the name of another\nentity, or where two entities share a title.\nNote that this is only for display purposes, and may be ignored by some\nparts of the code. Entity references still always make use of the `name`\nproperty, not the title.',
-              },
-              namespace: {
-                type: 'string',
-                description: 'The namespace that the entity belongs to.',
-              },
-              name: {
-                type: 'string',
-                description:
-                  'The name of the entity.\nMust be unique within the catalog at any given point in time, for any\ngiven namespace + kind pair. This value is part of the technical\nidentifier of the entity, and as such it will appear in URLs, database\ntables, entity references, and similar. It is subject to restrictions\nregarding what characters are allowed.\nIf you want to use a different, more human readable string with fewer\nrestrictions on it in user interfaces, see the `title` field below.',
-              },
-              etag: {
-                type: 'string',
-                description:
-                  'An opaque string that changes for each update operation to any part of\nthe entity, including metadata.\nThis field can not be set by the user at creation time, and the server\nwill reject an attempt to do so. The field will be populated in read\noperations. The field can (optionally) be specified when performing\nupdate or delete operations, and the server will then reject the\noperation if it does not match the current stored value.',
-              },
-              uid: {
-                type: 'string',
-                description:
-                  'A globally unique ID for the entity.\nThis field can not be set by the user at creation time, and the server\nwill reject an attempt to do so. The field will be populated in read\noperations. The field can (optionally) be specified when performing\nupdate or delete operations, but the server is free to reject requests\nthat do so in such a way that it breaks semantics.',
-              },
-            },
-            description:
-              'Metadata fields common to all versions/kinds of entity.',
-          },
-        ],
-        additionalProperties: false,
-      },
-      RecursivePartial_Entity_: {
-        type: 'object',
-        properties: {
-          apiVersion: {
-            type: 'string',
-            description:
-              'The version of specification format for this particular entity that\nthis is written against.',
-          },
-          kind: {
-            type: 'string',
-            description: 'The high level entity type being described.',
-          },
-          metadata: {
-            $ref: '#/components/schemas/RecursivePartialEntityMeta',
-          },
-          spec: {
-            $ref: '#/components/schemas/JsonObject',
-          },
-          relations: {
-            type: 'array',
-            items: {
-              $ref: '#/components/schemas/RecursivePartialEntityRelation',
-            },
-            description:
-              'The relations that this entity has with other entities.',
-          },
-        },
-        description: 'Makes all keys of an entire hierarchy optional.',
-        additionalProperties: false,
-      },
-      AnalyzeLocationEntityField: {
-        type: 'object',
-        properties: {
-          description: {
-            type: 'string',
-            description:
-              'A text to show to the user to inform about the choices made. Like, it could say\n"Found a CODEOWNERS file that covers this target, so we suggest leaving this \nfield empty; which would currently make it owned by X" where X is taken from the\ncodeowners file.',
-          },
-          value: {
-            type: 'string',
-            nullable: true,
-          },
-          state: {
-            type: 'string',
-            enum: [
-              'analysisSuggestedValue',
-              'analysisSuggestedNoValue',
-              'needsUserInput',
-            ],
-            description:
-              'The outcome of the analysis for this particular field',
-          },
-          field: {
-            type: 'string',
-            description:
-              'e.g. "spec.owner"? The frontend needs to know how to "inject" the field into the\nentity again if the user wants to change it',
-          },
-        },
-        required: ['description', 'value', 'state', 'field'],
-        additionalProperties: false,
-      },
-      AnalyzeLocationGenerateEntity: {
-        type: 'object',
-        properties: {
-          fields: {
-            type: 'array',
-            items: {
-              $ref: '#/components/schemas/AnalyzeLocationEntityField',
-            },
-          },
-          entity: {
-            $ref: '#/components/schemas/RecursivePartial_Entity_',
-          },
-        },
-        required: ['fields', 'entity'],
-        description:
-          "This is some form of representation of what the analyzer could deduce.\nWe should probably have a chat about how this can best be conveyed to\nthe frontend. It'll probably contain a (possibly incomplete) entity, plus\nenough info for the frontend to know what form data to show to the user\nfor overriding/completing the info.",
-        additionalProperties: false,
-      },
-      AnalyzeLocationResponse: {
-        type: 'object',
-        properties: {
-          generateEntities: {
-            items: {
-              $ref: '#/components/schemas/AnalyzeLocationGenerateEntity',
-            },
-            type: 'array',
-          },
-          existingEntityFiles: {
-            items: {
-              $ref: '#/components/schemas/AnalyzeLocationExistingEntity',
-            },
-            type: 'array',
-          },
-        },
-        required: ['generateEntities', 'existingEntityFiles'],
-        additionalProperties: false,
-      },
-      LocationInput: {
-        type: 'object',
-        properties: {
-          type: {
-            type: 'string',
-          },
-          target: {
-            type: 'string',
-          },
-          presence: {
-            type: 'string',
-            enum: ['optional', 'required'],
-          },
-        },
-        required: ['type', 'target', 'presence'],
-        additionalProperties: false,
-      },
-      SerializedError: {
-        allOf: [
-          {
-            $ref: '#/components/schemas/JsonObject',
-          },
-          {
-            type: 'object',
-            properties: {
-              code: {
-                type: 'string',
-                description:
-                  'A custom code (not necessarily the same as an HTTP response code); may not be present',
-              },
-              stack: {
-                type: 'string',
-                description: 'A stringified stack trace; may not be present',
-              },
-              message: {
-                type: 'string',
-                description: 'The message of the exception that was thrown',
-              },
-              name: {
-                type: 'string',
-                description: 'The name of the exception that was thrown',
-              },
-            },
-            required: ['message', 'name'],
-          },
-        ],
-        description: 'The serialized form of an Error.',
-        additionalProperties: false,
-      },
-      EntitiesQueryResponse: {
-        type: 'object',
-        properties: {
-          items: {
-            type: 'array',
-            items: {
-              $ref: '#/components/schemas/Entity',
-            },
-            description: 'The list of entities paginated by a specific filter.',
-          },
-          totalItems: {
-            type: 'number',
-          },
-          pageInfo: {
-            type: 'object',
-            properties: {
-              nextCursor: {
-                type: 'string',
-                description: 'Base64 encoded database query for the next page.',
-              },
-              prevCursor: {
-                type: 'string',
-                description:
-                  'Base64 encoded database query for the previous page.',
-              },
-            },
-          },
-        },
-        additionalProperties: false,
-      },
-    },
-    securitySchemes: {
-      JWT: {
-        type: 'http',
-        scheme: 'bearer',
-        bearerFormat: 'JWT',
-      },
-    },
-  },
-  paths: {
-    '/refresh': {
-      post: {
-        operationId: 'RefreshEntity',
-        responses: {
-          '200': {
-            description: 'Refreshed',
-          },
-        },
-        security: [
-          {},
-          {
-            JWT: [],
-          },
-        ],
-        parameters: [],
-        requestBody: {
-          required: true,
-          content: {
-            'application/json': {
-              schema: {
-                type: 'object',
-                properties: {
-                  authorizationToken: {
-                    type: 'string',
-                  },
-                  entityRef: {
-                    type: 'string',
-                    description:
-                      'The reference to a single entity that should be refreshed',
-                  },
-                },
-                required: ['entityRef'],
-                description:
-                  'Options for requesting a refresh of entities in the catalog.',
-                additionalProperties: false,
-              },
-            },
-          },
-        },
-      },
-    },
-    '/entities': {
-      get: {
-        operationId: 'GetEntities',
-        responses: {
-          '200': {
-            description: '',
-            content: {
-              'application/json': {
-                schema: {
-                  type: 'array',
-                  items: {
-                    $ref: '#/components/schemas/Entity',
-                  },
-                },
-              },
-            },
-          },
-        },
-        security: [
-          {},
-          {
-            JWT: [],
-          },
-        ],
-        parameters: [
-          {
-            in: 'query',
-            name: 'filter',
-            required: false,
-            schema: {
-              type: 'string',
-            },
-          },
-          {
-            in: 'query',
-            name: 'fields',
-            required: false,
-            schema: {
-              type: 'string',
-            },
-          },
-          {
-            in: 'query',
-            name: 'offset',
-            required: false,
-            schema: {
-              type: 'string',
-            },
-          },
-          {
-            in: 'query',
-            name: 'limit',
-            required: false,
-            schema: {
-              type: 'string',
-            },
-          },
-          {
-            in: 'query',
-            name: 'after',
-            required: false,
-            schema: {
-              type: 'string',
-            },
-          },
-        ],
-      },
-    },
-    '/entities/by-uid/{uid}': {
-      get: {
-        operationId: 'GetEntityByUid',
-        responses: {
-          '200': {
-            description: 'Ok',
-            content: {
-              'application/json': {
-                schema: {
-                  $ref: '#/components/schemas/Entity',
-                },
-              },
-            },
-          },
-        },
-        security: [
-          {},
-          {
-            JWT: [],
-          },
-        ],
-        parameters: [
-          {
-            in: 'path',
-            name: 'uid',
-            required: true,
-            schema: {
-              type: 'string',
-            },
-          },
-        ],
-      },
-      delete: {
-        operationId: 'DeleteEntityByUid',
-        responses: {
-          '204': {
-            description: 'Deleted successfully.',
-          },
-        },
-        security: [
-          {},
-          {
-            JWT: [],
-          },
-        ],
-        parameters: [
-          {
-            in: 'path',
-            name: 'uid',
-            required: true,
-            schema: {
-              type: 'string',
-            },
-          },
-        ],
-      },
-    },
-    '/entities/by-name/{kind}/{namespace}/{name}': {
-      get: {
-        operationId: 'GetEntityByName',
-        responses: {
-          '200': {
-            description: 'Ok',
-            content: {
-              'application/json': {
-                schema: {
-                  $ref: '#/components/schemas/Entity',
-                },
-              },
-            },
-          },
-        },
-        security: [
-          {},
-          {
-            JWT: [],
-          },
-        ],
-        parameters: [
-          {
-            in: 'path',
-            name: 'kind',
-            required: true,
-            schema: {
-              type: 'string',
-            },
-          },
-          {
-            in: 'path',
-            name: 'namespace',
-            required: true,
-            schema: {
-              type: 'string',
-            },
-          },
-          {
-            in: 'path',
-            name: 'name',
-            required: true,
-            schema: {
-              type: 'string',
-            },
-          },
-        ],
-      },
-    },
-    '/entities/by-name/{kind}/{namespace}/{name}/ancestry': {
-      get: {
-        operationId: 'GetEntityAncestryByName',
-        responses: {
-          '200': {
-            description: 'Ok',
-            content: {
-              'application/json': {
-                schema: {
-                  $ref: '#/components/schemas/EntityAncestryResponse',
-                },
-              },
-            },
-          },
-        },
-        security: [
-          {},
-          {
-            JWT: [],
-          },
-        ],
-        parameters: [
-          {
-            in: 'path',
-            name: 'kind',
-            required: true,
-            schema: {
-              type: 'string',
-            },
-          },
-          {
-            in: 'path',
-            name: 'namespace',
-            required: true,
-            schema: {
-              type: 'string',
-            },
-          },
-          {
-            in: 'path',
-            name: 'name',
-            required: true,
-            schema: {
-              type: 'string',
-            },
-          },
-        ],
-      },
-    },
-    '/entities/by-refs': {
-      post: {
-        operationId: 'GetEntitiesByRefs',
-        responses: {
-          '200': {
-            description: 'Ok',
-            content: {
-              'application/json': {
-                schema: {
-                  $ref: '#/components/schemas/EntitiesBatchResponse',
-                },
-              },
-            },
-          },
-        },
-        security: [
-          {},
-          {
-            JWT: [],
-          },
-        ],
-        parameters: [
-          {
-            in: 'query',
-            name: 'fields',
-            required: false,
-            schema: {
-              type: 'string',
-            },
-          },
-        ],
-        requestBody: {
-          required: true,
-          content: {
-            'application/json': {
-              schema: {
-                type: 'array',
-                items: {
-                  type: 'string',
-                },
-              },
-            },
-          },
-        },
-      },
-    },
-    '/entities/by-query': {
-      get: {
-        operationId: 'GetEntitiesByQuery',
-        responses: {
-          '200': {
-            description: 'Ok',
-            content: {
-              'application/json': {
-                schema: {
-                  $ref: '#/components/schemas/EntitiesQueryResponse',
-                },
-              },
-            },
-          },
-        },
-        security: [
-          {},
-          {
-            JWT: [],
-          },
-        ],
-        parameters: [
-          {
-            in: 'query',
-            name: 'fields',
-            required: false,
-            schema: {
-              type: 'string',
-            },
-          },
-        ],
-        requestBody: {
-          required: true,
-          content: {
-            'application/json': {
-              schema: {
-                type: 'array',
-                items: {
-                  type: 'string',
-                },
-              },
-            },
-          },
-        },
-      },
-    },
-    '/entity-facets': {
-      get: {
-        operationId: 'GetEntityFacets',
-        responses: {
-          '200': {
-            description: 'Ok',
-            content: {
-              'application/json': {
-                schema: {
-                  $ref: '#/components/schemas/EntityFacetsResponse',
-                },
-              },
-            },
-          },
-        },
-        security: [
-          {},
-          {
-            JWT: [],
-          },
-        ],
-        parameters: [
-          {
-            in: 'query',
-            name: 'facet',
-            required: true,
-            schema: {
-              type: 'string',
-            },
-          },
-          {
-            in: 'query',
-            name: 'filter',
-            required: false,
-            schema: {
-              type: 'string',
-            },
-          },
-        ],
-      },
-    },
-    '/locations': {
-      post: {
-        operationId: 'CreateLocation',
-        responses: {
-          '200': {
-            description: 'Ok',
-            content: {
-              'application/json': {
-                schema: {
-                  type: 'object',
-                  properties: {
-                    exists: {
-                      type: 'boolean',
-                    },
-                    entities: {
-                      items: {
-                        $ref: '#/components/schemas/Entity',
-                      },
-                      type: 'array',
-                    },
-                    location: {
-                      $ref: '#/components/schemas/Location',
-                    },
-                  },
-                  required: ['entities', 'location'],
-                },
-              },
-            },
-          },
-        },
-        security: [
-          {},
-          {
-            JWT: [],
-          },
-        ],
-        parameters: [
-          {
-            in: 'query',
-            name: 'dryRun',
-            required: false,
-            schema: {
-              type: 'boolean',
-            },
-          },
-        ],
-        requestBody: {
-          required: true,
-          content: {
-            'application/json': {
-              schema: {
-                type: 'object',
-                properties: {
-                  presence: {
-                    type: 'string',
-                    enum: ['required', 'optional'],
-                  },
-                  target: {
-                    type: 'string',
-                  },
-                  type: {
-                    type: 'string',
-                  },
-                },
-                required: ['presence', 'target', 'type'],
-              },
-            },
-          },
-        },
-      },
-      get: {
-        operationId: 'GetLocations',
-        responses: {
-          '200': {
-            description: 'Ok',
-            content: {
-              'application/json': {
-                schema: {
-                  type: 'array',
-                  items: {
-                    type: 'object',
-                    properties: {
-                      data: {
-                        $ref: '#/components/schemas/Location',
-                      },
-                    },
-                    required: ['data'],
-                  },
-                },
-              },
-            },
-          },
-        },
-        security: [
-          {},
-          {
-            JWT: [],
-          },
-        ],
-        parameters: [],
-      },
-    },
-    '/locations/{id}': {
-      get: {
-        operationId: 'GetLocation',
-        responses: {
-          '200': {
-            description: 'Ok',
-            content: {
-              'application/json': {
-                schema: {
-                  $ref: '#/components/schemas/Location',
-                },
-              },
-            },
-          },
-        },
-        security: [
-          {},
-          {
-            JWT: [],
-          },
-        ],
-        parameters: [
-          {
-            in: 'path',
-            name: 'id',
-            required: true,
-            schema: {
-              type: 'string',
-            },
-          },
-        ],
-      },
-      delete: {
-        operationId: 'DeleteLocation',
-        responses: {
-          '204': {
-            description: 'No content',
-          },
-        },
-        security: [
-          {},
-          {
-            JWT: [],
-          },
-        ],
-        parameters: [
-          {
-            in: 'path',
-            name: 'id',
-            required: true,
-            schema: {
-              type: 'string',
-            },
-          },
-        ],
-      },
-    },
-    '/analyze-location': {
-      post: {
-        operationId: 'AnalyzeLocation',
-        responses: {
-          '200': {
-            description: 'Ok',
-            content: {
-              'application/json': {
-                schema: {
-                  $ref: '#/components/schemas/AnalyzeLocationResponse',
-                },
-              },
-            },
-          },
-        },
-        security: [
-          {},
-          {
-            JWT: [],
-          },
-        ],
-        parameters: [],
-        requestBody: {
-          required: true,
-          content: {
-            'application/json': {
-              schema: {
-                type: 'object',
-                properties: {
-                  catalogFileName: {
-                    type: 'string',
-                  },
-                  location: {
-                    $ref: '#/components/schemas/LocationInput',
-                  },
-                },
-                required: ['catalogFileName', 'location'],
-              },
-            },
-          },
-        },
-      },
-    },
-    '/validate-entity': {
-      post: {
-        operationId: 'ValidateEntity',
-        responses: {
-          '200': {
-            description: 'Ok',
-            content: {
-              'application/json': {
-                schema: {
-                  anyOf: [
-                    {
-                      type: 'object',
-                      properties: {
-                        errors: {
-                          $ref: '#/components/schemas/SerializedError',
-                        },
-                      },
-                      required: ['errors'],
-                    },
-                    {
-                      type: 'object',
-                      properties: {
-                        errors: {
-                          type: 'array',
-                          items: {
-                            $ref: '#/components/schemas/SerializedError',
-                          },
-                        },
-                      },
-                      required: ['errors'],
-                    },
-                  ],
-                },
-              },
-            },
-          },
-        },
-        security: [
-          {},
-          {
-            JWT: [],
-          },
-        ],
-        parameters: [],
-        requestBody: {
-          required: true,
-          content: {
-            'application/json': {
-              schema: {
-                type: 'object',
-                properties: {
-                  location: {
-                    type: 'string',
-                  },
-                  entity: {
-                    $ref: '#/components/schemas/Entity',
-                  },
-                },
-                required: ['location', 'entity'],
-              },
-            },
-          },
-        },
-      },
-    },
-  },
-} as const;
diff --git a/plugins/openapi-router-common/src/types/common.ts b/plugins/openapi-router-common/src/types/common.ts
index 62f9a7bcee..27643421f3 100644
--- a/plugins/openapi-router-common/src/types/common.ts
+++ b/plugins/openapi-router-common/src/types/common.ts
@@ -19,11 +19,7 @@
  */
 
 import { FromSchema, JSONSchema7 } from 'json-schema-to-ts';
-import type {
-  ContentObject,
-  OpenAPIObject,
-  ReferenceObject,
-} from 'openapi3-ts';
+import { ContentObject, OpenAPIObject, ReferenceObject } from './immutable';
 
 /**
  * Basic OpenAPI spec with paths and components properties enforced.
diff --git a/plugins/openapi-router-common/src/types/immutable.ts b/plugins/openapi-router-common/src/types/immutable.ts
new file mode 100644
index 0000000000..1b323950bf
--- /dev/null
+++ b/plugins/openapi-router-common/src/types/immutable.ts
@@ -0,0 +1,51 @@
+/*
+ * Copyright 2023 The Backstage Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import type {
+  ContentObject as MutableContentObject,
+  OpenAPIObject as MutableOpenApiObject,
+  ReferenceObject as MutableReferenceObject,
+  RequestBodyObject as MutableRequestBodyObject,
+} from 'openapi3-ts';
+
+/**
+ * This file is meant to hold Immutable overwrites of the values provided by the `openapi3-ts`
+ *  package due to issues with `as const` supporting only readonly values.
+ */
+
+export type Immutable<T> = T extends
+  | Function
+  | boolean
+  | number
+  | string
+  | null
+  | undefined
+  ? T
+  : T extends Map<infer K, infer V>
+  ? ReadonlyMap<Immutable<K>, Immutable<V>>
+  : T extends Set<infer S>
+  ? ReadonlySet<Immutable<S>>
+  : { readonly [P in keyof T]: Immutable<T[P]> };
+
+// This works for objects, arrays and tuples:
+export type ImmutableObject<T> = { readonly [K in keyof T]: Immutable<T[K]> };
+
+export type ReferenceObject = ImmutableObject<MutableReferenceObject>;
+
+export type OpenAPIObject = ImmutableObject<MutableOpenApiObject>;
+
+export type ContentObject = ImmutableObject<MutableContentObject>;
+
+export type RequestBodyObject = ImmutableObject<MutableRequestBodyObject>;
diff --git a/plugins/openapi-router-common/src/types/requests.ts b/plugins/openapi-router-common/src/types/requests.ts
index 04c0a30f3a..e243be63e1 100644
--- a/plugins/openapi-router-common/src/types/requests.ts
+++ b/plugins/openapi-router-common/src/types/requests.ts
@@ -18,7 +18,6 @@
  * Pulled from https://github.com/varanauskas/oatx.
  */
 
-import type { ReferenceObject, RequestBodyObject } from 'openapi3-ts';
 import type {
   ComponentRef,
   ComponentTypes,
@@ -31,6 +30,7 @@ import type {
   PathTemplate,
   ToTypeSafe,
 } from './common';
+import { ReferenceObject, RequestBodyObject } from './immutable';
 
 /**
  * @public

From 8bb18ff229d0e51d1517f9cf1b36236f13daec88 Mon Sep 17 00:00:00 2001
From: Aramis Sennyey <sennyeya@amazon.com>
Date: Tue, 28 Feb 2023 14:05:30 -0500
Subject: [PATCH 26/61] Add Immutable prefix.

Signed-off-by: Aramis Sennyey <sennyeya@amazon.com>
---
 plugins/openapi-router-common/api-report.md   | 63 +++++++++++++++----
 .../openapi-router-common/src/types/common.ts | 18 +++---
 .../src/types/immutable.ts                    | 37 ++++++++---
 .../openapi-router-common/src/types/index.ts  |  1 +
 .../src/types/requests.ts                     | 17 ++++-
 5 files changed, 104 insertions(+), 32 deletions(-)

diff --git a/plugins/openapi-router-common/api-report.md b/plugins/openapi-router-common/api-report.md
index de82f1e5c7..5c09d0432d 100644
--- a/plugins/openapi-router-common/api-report.md
+++ b/plugins/openapi-router-common/api-report.md
@@ -37,12 +37,12 @@ export interface ApiRouter<Doc extends RequiredDoc> extends Router {
 export type ComponentRef<
   Doc extends RequiredDoc,
   Type extends ComponentTypes<Doc>,
-  Ref extends ReferenceObject,
+  Ref extends ImmutableReferenceObject,
 > = Ref extends {
   $ref: `#/components/${Type}/${infer Name}`;
 }
   ? Name extends keyof Doc['components'][Type]
-    ? Doc['components'][Type][Name] extends ReferenceObject
+    ? Doc['components'][Type][Name] extends ImmutableReferenceObject
       ? ComponentRef<Doc, Type, Doc['components'][Type][Name]>
       : Doc['components'][Type][Name]
     : never
@@ -62,11 +62,6 @@ export type ConvertAll<T, R extends ReadonlyArray<unknown> = []> = T extends [
   ? ConvertAll<Rest, [...R, FromSchema<First>]>
   : R;
 
-// @public
-export type DeepWriteable<T> = {
-  -readonly [P in keyof T]: DeepWriteable<T[P]>;
-};
-
 // @public (undocumented)
 export type DocOperation<
   Doc extends RequiredDoc,
@@ -148,6 +143,40 @@ export interface DocRequestMatcher<
   ): T;
 }
 
+// @public
+export type Immutable<T> = T extends
+  | Function
+  | boolean
+  | number
+  | string
+  | null
+  | undefined
+  ? T
+  : T extends Map<infer K, infer V>
+  ? ReadonlyMap<Immutable<K>, Immutable<V>>
+  : T extends Set<infer S>
+  ? ReadonlySet<Immutable<S>>
+  : {
+      readonly [P in keyof T]: Immutable<T[P]>;
+    };
+
+// @public (undocumented)
+export type ImmutableContentObject = ImmutableObject<ContentObject>;
+
+// @public (undocumented)
+export type ImmutableObject<T> = {
+  readonly [K in keyof T]: Immutable<T[K]>;
+};
+
+// @public (undocumented)
+export type ImmutableOpenAPIObject = ImmutableObject<OpenAPIObject>;
+
+// @public (undocumented)
+export type ImmutableReferenceObject = ImmutableObject<ReferenceObject>;
+
+// @public (undocumented)
+export type ImmutableRequestBodyObject = ImmutableObject<RequestBodyObject>;
+
 // @public (undocumented)
 export type LastOf<T> = UnionToIntersection<
   T extends any ? () => T : never
@@ -175,9 +204,9 @@ export type MethodAwareDocPath<
 export type ObjectWithContentSchema<
   Doc extends RequiredDoc,
   Object extends {
-    content?: ContentObject;
+    content?: ImmutableContentObject;
   },
-> = Object['content'] extends ContentObject
+> = Object['content'] extends ImmutableContentObject
   ? SchemaRef<Doc, Object['content']['application/json']['schema']>
   : never;
 
@@ -188,7 +217,7 @@ export interface ParsedQs {
 }
 
 // @public (undocumented)
-export type PathDoc = Pick<OpenAPIObject, 'paths'>;
+export type PathDoc = Pick<ImmutableOpenAPIObject, 'paths'>;
 
 // @public
 export type PathTemplate<Path extends string> =
@@ -204,7 +233,11 @@ export type RequestBody<
   Doc extends RequiredDoc,
   Path extends Extract<keyof Doc['paths'], string>,
   Method extends keyof Doc['paths'][Path],
-> = DocOperation<Doc, Path, Method>['requestBody'] extends ReferenceObject
+> = DocOperation<
+  Doc,
+  Path,
+  Method
+>['requestBody'] extends ImmutableReferenceObject
   ? 'requestBodies' extends ComponentTypes<Doc>
     ? ComponentRef<
         Doc,
@@ -219,7 +252,11 @@ export type RequestBodySchema<
   Doc extends RequiredDoc,
   Path extends DocPathTemplate<Doc>,
   Method extends DocPathMethod<Doc, Path>,
-> = RequestBody<Doc, DocPath<Doc, Path>, Method> extends RequestBodyObject
+> = RequestBody<
+  Doc,
+  DocPath<Doc, Path>,
+  Method
+> extends ImmutableRequestBodyObject
   ? ObjectWithContentSchema<Doc, RequestBody<Doc, DocPath<Doc, Path>, Method>>
   : never;
 
@@ -231,7 +268,7 @@ export type RequestBodyToJsonSchema<
 > = ToTypeSafe<RequestBodySchema<Doc, Path, Method>>;
 
 // @public
-export type RequiredDoc = Pick<OpenAPIObject, 'paths' | 'components'>;
+export type RequiredDoc = Pick<ImmutableOpenAPIObject, 'paths' | 'components'>;
 
 // @public (undocumented)
 type Response_2<
diff --git a/plugins/openapi-router-common/src/types/common.ts b/plugins/openapi-router-common/src/types/common.ts
index 27643421f3..ac1fc29b84 100644
--- a/plugins/openapi-router-common/src/types/common.ts
+++ b/plugins/openapi-router-common/src/types/common.ts
@@ -19,19 +19,23 @@
  */
 
 import { FromSchema, JSONSchema7 } from 'json-schema-to-ts';
-import { ContentObject, OpenAPIObject, ReferenceObject } from './immutable';
+import {
+  ImmutableContentObject,
+  ImmutableOpenAPIObject,
+  ImmutableReferenceObject,
+} from './immutable';
 
 /**
  * Basic OpenAPI spec with paths and components properties enforced.
  *
  * @public
  */
-export type RequiredDoc = Pick<OpenAPIObject, 'paths' | 'components'>;
+export type RequiredDoc = Pick<ImmutableOpenAPIObject, 'paths' | 'components'>;
 
 /**
  * @public
  */
-export type PathDoc = Pick<OpenAPIObject, 'paths'>;
+export type PathDoc = Pick<ImmutableOpenAPIObject, 'paths'>;
 
 /**
  * Get value types of `T`
@@ -140,10 +144,10 @@ export type ComponentTypes<Doc extends RequiredDoc> = Extract<
 export type ComponentRef<
   Doc extends RequiredDoc,
   Type extends ComponentTypes<Doc>,
-  Ref extends ReferenceObject,
+  Ref extends ImmutableReferenceObject,
 > = Ref extends { $ref: `#/components/${Type}/${infer Name}` }
   ? Name extends keyof Doc['components'][Type]
-    ? Doc['components'][Type][Name] extends ReferenceObject
+    ? Doc['components'][Type][Name] extends ImmutableReferenceObject
       ? ComponentRef<Doc, Type, Doc['components'][Type][Name]>
       : Doc['components'][Type][Name]
     : never
@@ -167,8 +171,8 @@ export type SchemaRef<Doc extends RequiredDoc, Schema> = Schema extends {
  */
 export type ObjectWithContentSchema<
   Doc extends RequiredDoc,
-  Object extends { content?: ContentObject },
-> = Object['content'] extends ContentObject
+  Object extends { content?: ImmutableContentObject },
+> = Object['content'] extends ImmutableContentObject
   ? SchemaRef<Doc, Object['content']['application/json']['schema']>
   : never;
 
diff --git a/plugins/openapi-router-common/src/types/immutable.ts b/plugins/openapi-router-common/src/types/immutable.ts
index 1b323950bf..dec20105cf 100644
--- a/plugins/openapi-router-common/src/types/immutable.ts
+++ b/plugins/openapi-router-common/src/types/immutable.ts
@@ -14,10 +14,10 @@
  * limitations under the License.
  */
 import type {
-  ContentObject as MutableContentObject,
-  OpenAPIObject as MutableOpenApiObject,
-  ReferenceObject as MutableReferenceObject,
-  RequestBodyObject as MutableRequestBodyObject,
+  ContentObject,
+  OpenAPIObject,
+  ReferenceObject,
+  RequestBodyObject,
 } from 'openapi3-ts';
 
 /**
@@ -25,6 +25,11 @@ import type {
  *  package due to issues with `as const` supporting only readonly values.
  */
 
+/**
+ * From {@link https://github.com/microsoft/TypeScript/issues/13923#issuecomment-653675557}, allows
+ *  us to convert from `as const` to the various OpenAPI types documented in `openapi3-ts`.
+ * @public
+ */
 export type Immutable<T> = T extends
   | Function
   | boolean
@@ -39,13 +44,27 @@ export type Immutable<T> = T extends
   ? ReadonlySet<Immutable<S>>
   : { readonly [P in keyof T]: Immutable<T[P]> };
 
-// This works for objects, arrays and tuples:
+/**
+ * @public
+ */
 export type ImmutableObject<T> = { readonly [K in keyof T]: Immutable<T[K]> };
 
-export type ReferenceObject = ImmutableObject<MutableReferenceObject>;
+/**
+ * @public
+ */
+export type ImmutableReferenceObject = ImmutableObject<ReferenceObject>;
 
-export type OpenAPIObject = ImmutableObject<MutableOpenApiObject>;
+/**
+ * @public
+ */
+export type ImmutableOpenAPIObject = ImmutableObject<OpenAPIObject>;
 
-export type ContentObject = ImmutableObject<MutableContentObject>;
+/**
+ * @public
+ */
+export type ImmutableContentObject = ImmutableObject<ContentObject>;
 
-export type RequestBodyObject = ImmutableObject<MutableRequestBodyObject>;
+/**
+ * @public
+ */
+export type ImmutableRequestBodyObject = ImmutableObject<RequestBodyObject>;
diff --git a/plugins/openapi-router-common/src/types/index.ts b/plugins/openapi-router-common/src/types/index.ts
index 8862161ac0..1a1f5265bf 100644
--- a/plugins/openapi-router-common/src/types/index.ts
+++ b/plugins/openapi-router-common/src/types/index.ts
@@ -17,3 +17,4 @@ export * from './common';
 export * from './express';
 export * from './requests';
 export * from './responses';
+export * from './immutable';
diff --git a/plugins/openapi-router-common/src/types/requests.ts b/plugins/openapi-router-common/src/types/requests.ts
index e243be63e1..e6542e186d 100644
--- a/plugins/openapi-router-common/src/types/requests.ts
+++ b/plugins/openapi-router-common/src/types/requests.ts
@@ -30,7 +30,10 @@ import type {
   PathTemplate,
   ToTypeSafe,
 } from './common';
-import { ReferenceObject, RequestBodyObject } from './immutable';
+import {
+  ImmutableReferenceObject,
+  ImmutableRequestBodyObject,
+} from './immutable';
 
 /**
  * @public
@@ -39,7 +42,11 @@ export type RequestBody<
   Doc extends RequiredDoc,
   Path extends Extract<keyof Doc['paths'], string>,
   Method extends keyof Doc['paths'][Path],
-> = DocOperation<Doc, Path, Method>['requestBody'] extends ReferenceObject
+> = DocOperation<
+  Doc,
+  Path,
+  Method
+>['requestBody'] extends ImmutableReferenceObject
   ? 'requestBodies' extends ComponentTypes<Doc>
     ? ComponentRef<
         Doc,
@@ -56,7 +63,11 @@ export type RequestBodySchema<
   Doc extends RequiredDoc,
   Path extends DocPathTemplate<Doc>,
   Method extends DocPathMethod<Doc, Path>,
-> = RequestBody<Doc, DocPath<Doc, Path>, Method> extends RequestBodyObject
+> = RequestBody<
+  Doc,
+  DocPath<Doc, Path>,
+  Method
+> extends ImmutableRequestBodyObject
   ? ObjectWithContentSchema<Doc, RequestBody<Doc, DocPath<Doc, Path>, Method>>
   : never;
 

From 2cc50f71c496dd60325f2ab89c1c32063bacb28e Mon Sep 17 00:00:00 2001
From: Aramis Sennyey <sennyeya@amazon.com>
Date: Thu, 2 Mar 2023 11:31:14 -0500
Subject: [PATCH 27/61] Update package name and add more details in the README.

Signed-off-by: Aramis Sennyey <sennyeya@amazon.com>
---
 plugins/openapi-router-common/README.md       |  5 --
 .../.eslintrc.js                              |  0
 plugins/openapi-router/README.md              | 60 +++++++++++++++++++
 .../api-report.md                             |  0
 .../package.json                              |  0
 .../src/example.ts                            |  0
 .../src/index.ts                              |  0
 .../src/router.ts                             |  8 ---
 .../src/run.ts                                |  0
 .../src/schema/petstore.ts                    |  0
 .../src/setupTests.ts                         |  0
 .../src/standaloneServer.ts                   |  0
 .../src/types/common.ts                       |  0
 .../src/types/express.ts                      |  0
 .../src/types/immutable.ts                    |  0
 .../src/types/index.ts                        |  0
 .../src/types/requests.ts                     |  0
 .../src/types/responses.ts                    |  0
 yarn.lock                                     |  4 +-
 19 files changed, 62 insertions(+), 15 deletions(-)
 delete mode 100644 plugins/openapi-router-common/README.md
 rename plugins/{openapi-router-common => openapi-router}/.eslintrc.js (100%)
 create mode 100644 plugins/openapi-router/README.md
 rename plugins/{openapi-router-common => openapi-router}/api-report.md (100%)
 rename plugins/{openapi-router-common => openapi-router}/package.json (100%)
 rename plugins/{openapi-router-common => openapi-router}/src/example.ts (100%)
 rename plugins/{openapi-router-common => openapi-router}/src/index.ts (100%)
 rename plugins/{openapi-router-common => openapi-router}/src/router.ts (87%)
 rename plugins/{openapi-router-common => openapi-router}/src/run.ts (100%)
 rename plugins/{openapi-router-common => openapi-router}/src/schema/petstore.ts (100%)
 rename plugins/{openapi-router-common => openapi-router}/src/setupTests.ts (100%)
 rename plugins/{openapi-router-common => openapi-router}/src/standaloneServer.ts (100%)
 rename plugins/{openapi-router-common => openapi-router}/src/types/common.ts (100%)
 rename plugins/{openapi-router-common => openapi-router}/src/types/express.ts (100%)
 rename plugins/{openapi-router-common => openapi-router}/src/types/immutable.ts (100%)
 rename plugins/{openapi-router-common => openapi-router}/src/types/index.ts (100%)
 rename plugins/{openapi-router-common => openapi-router}/src/types/requests.ts (100%)
 rename plugins/{openapi-router-common => openapi-router}/src/types/responses.ts (100%)

diff --git a/plugins/openapi-router-common/README.md b/plugins/openapi-router-common/README.md
deleted file mode 100644
index cda5d7fc7f..0000000000
--- a/plugins/openapi-router-common/README.md
+++ /dev/null
@@ -1,5 +0,0 @@
-# @backstage/plugin-openapi-router-common
-
-Welcome to the common package for the openapi-router plugin!
-
-_This plugin was created through the Backstage CLI_
diff --git a/plugins/openapi-router-common/.eslintrc.js b/plugins/openapi-router/.eslintrc.js
similarity index 100%
rename from plugins/openapi-router-common/.eslintrc.js
rename to plugins/openapi-router/.eslintrc.js
diff --git a/plugins/openapi-router/README.md b/plugins/openapi-router/README.md
new file mode 100644
index 0000000000..ad45dae773
--- /dev/null
+++ b/plugins/openapi-router/README.md
@@ -0,0 +1,60 @@
+# @backstage/plugin-openapi-router
+
+## Purpose
+
+This package is meant to provide a typed Express router for an OpenAPI spec. Specs must be converted to JSON and then copied to a Typescript file.
+
+## Getting Started
+
+### Configuration
+
+In your plugin's `schema/openapi`,
+
+```ts
+export default {
+  // If your spec is in YAML, convert it to JSON, then paste it here.
+  // If your spec is in JSON, just paste it here.
+} as const;
+```
+
+In your plugin's `service/createRouter.ts`,
+
+```ts
+import {ApiRouter} from `@backstage/plugin-openapi-router`;
+import spec from './schema/openapi'
+...
+
+export function createRouter(){
+    const router = Router() as ApiRouter<typeof spec>
+}
+```
+
+### Limitations
+
+1. OpenAPI definitions must be converted to Typescript files
+   From [#32063](https://github.com/microsoft/TypeScript/issues/32063), we cannot import JSON `as const`. If we could, this would allow us to force all specs to be JSON and then just import from a spec.
+2. `as const` makes all fields `readonly`
+   To ensure a good DX of
+
+```tsx
+...
+Router() as ApiRouter<typeof spec>
+...
+```
+
+we need to type all internals of this package as `Immutable<T>`.
+
+## Future Work
+
+### Automatic generation of the `schema/openapi` file
+
+Ideally, this would be automatically generated on `openapi.yaml` updates (like a Webpack plugin), but could also be a CLI command.
+
+### Runtime validation
+
+Using a package like [`express-openapi-validator`](https://www.npmjs.com/package/express-openapi-validator), would allow us to remove [validation of request bodies with `AJV`](https://github.com/backstage/backstage/blob/master/plugins/catalog-backend/src/service/util.ts#L58).
+
+### PR-time verification.
+
+1. Verify that Typescript file matches the spec file.
+2. Verify that spec file matches the router input/output.
diff --git a/plugins/openapi-router-common/api-report.md b/plugins/openapi-router/api-report.md
similarity index 100%
rename from plugins/openapi-router-common/api-report.md
rename to plugins/openapi-router/api-report.md
diff --git a/plugins/openapi-router-common/package.json b/plugins/openapi-router/package.json
similarity index 100%
rename from plugins/openapi-router-common/package.json
rename to plugins/openapi-router/package.json
diff --git a/plugins/openapi-router-common/src/example.ts b/plugins/openapi-router/src/example.ts
similarity index 100%
rename from plugins/openapi-router-common/src/example.ts
rename to plugins/openapi-router/src/example.ts
diff --git a/plugins/openapi-router-common/src/index.ts b/plugins/openapi-router/src/index.ts
similarity index 100%
rename from plugins/openapi-router-common/src/index.ts
rename to plugins/openapi-router/src/index.ts
diff --git a/plugins/openapi-router-common/src/router.ts b/plugins/openapi-router/src/router.ts
similarity index 87%
rename from plugins/openapi-router-common/src/router.ts
rename to plugins/openapi-router/src/router.ts
index 3d46f7ce6f..15f4fe9b7a 100644
--- a/plugins/openapi-router-common/src/router.ts
+++ b/plugins/openapi-router/src/router.ts
@@ -16,14 +16,6 @@
 import { Router } from 'express';
 import { RequiredDoc, DocRequestMatcher } from './types';
 
-/**
- * Helper to transform readonly `as const` API specs for the ApiRouter.
- * @public
- */
-export type DeepReadonly<T> = {
-  readonly [P in keyof T]: DeepReadonly<T[P]>;
-};
-
 /**
  * Typed Express router based on an OpenAPI 3.1 spec.
  * @public
diff --git a/plugins/openapi-router-common/src/run.ts b/plugins/openapi-router/src/run.ts
similarity index 100%
rename from plugins/openapi-router-common/src/run.ts
rename to plugins/openapi-router/src/run.ts
diff --git a/plugins/openapi-router-common/src/schema/petstore.ts b/plugins/openapi-router/src/schema/petstore.ts
similarity index 100%
rename from plugins/openapi-router-common/src/schema/petstore.ts
rename to plugins/openapi-router/src/schema/petstore.ts
diff --git a/plugins/openapi-router-common/src/setupTests.ts b/plugins/openapi-router/src/setupTests.ts
similarity index 100%
rename from plugins/openapi-router-common/src/setupTests.ts
rename to plugins/openapi-router/src/setupTests.ts
diff --git a/plugins/openapi-router-common/src/standaloneServer.ts b/plugins/openapi-router/src/standaloneServer.ts
similarity index 100%
rename from plugins/openapi-router-common/src/standaloneServer.ts
rename to plugins/openapi-router/src/standaloneServer.ts
diff --git a/plugins/openapi-router-common/src/types/common.ts b/plugins/openapi-router/src/types/common.ts
similarity index 100%
rename from plugins/openapi-router-common/src/types/common.ts
rename to plugins/openapi-router/src/types/common.ts
diff --git a/plugins/openapi-router-common/src/types/express.ts b/plugins/openapi-router/src/types/express.ts
similarity index 100%
rename from plugins/openapi-router-common/src/types/express.ts
rename to plugins/openapi-router/src/types/express.ts
diff --git a/plugins/openapi-router-common/src/types/immutable.ts b/plugins/openapi-router/src/types/immutable.ts
similarity index 100%
rename from plugins/openapi-router-common/src/types/immutable.ts
rename to plugins/openapi-router/src/types/immutable.ts
diff --git a/plugins/openapi-router-common/src/types/index.ts b/plugins/openapi-router/src/types/index.ts
similarity index 100%
rename from plugins/openapi-router-common/src/types/index.ts
rename to plugins/openapi-router/src/types/index.ts
diff --git a/plugins/openapi-router-common/src/types/requests.ts b/plugins/openapi-router/src/types/requests.ts
similarity index 100%
rename from plugins/openapi-router-common/src/types/requests.ts
rename to plugins/openapi-router/src/types/requests.ts
diff --git a/plugins/openapi-router-common/src/types/responses.ts b/plugins/openapi-router/src/types/responses.ts
similarity index 100%
rename from plugins/openapi-router-common/src/types/responses.ts
rename to plugins/openapi-router/src/types/responses.ts
diff --git a/yarn.lock b/yarn.lock
index 91df44aac6..7601b411e7 100644
--- a/yarn.lock
+++ b/yarn.lock
@@ -7794,9 +7794,9 @@ __metadata:
   languageName: unknown
   linkType: soft
 
-"@backstage/plugin-openapi-router@workspace:^, @backstage/plugin-openapi-router@workspace:plugins/openapi-router-common":
+"@backstage/plugin-openapi-router@workspace:^, @backstage/plugin-openapi-router@workspace:plugins/openapi-router":
   version: 0.0.0-use.local
-  resolution: "@backstage/plugin-openapi-router@workspace:plugins/openapi-router-common"
+  resolution: "@backstage/plugin-openapi-router@workspace:plugins/openapi-router"
   dependencies:
     "@backstage/backend-common": "workspace:^"
     "@backstage/cli": "workspace:^"

From 96f8fe1fa404f7d5048a93020f4bbac000aca942 Mon Sep 17 00:00:00 2001
From: Aramis Sennyey <sennyeya@amazon.com>
Date: Thu, 2 Mar 2023 16:35:58 -0500
Subject: [PATCH 28/61] Testing for parameter typings.

Signed-off-by: Aramis Sennyey <sennyeya@amazon.com>
---
 .husky/pre-commit                             |  2 +-
 plugins/openapi-router/package.json           |  3 +-
 plugins/openapi-router/src/types/immutable.ts | 31 ++++++
 plugins/openapi-router/src/types/params.ts    | 96 +++++++++++++++++++
 yarn.lock                                     |  8 ++
 5 files changed, 138 insertions(+), 2 deletions(-)
 create mode 100644 plugins/openapi-router/src/types/params.ts

diff --git a/.husky/pre-commit b/.husky/pre-commit
index d2ae35e84b..8862d8db03 100755
--- a/.husky/pre-commit
+++ b/.husky/pre-commit
@@ -1,4 +1,4 @@
-#!/bin/sh
+#!/bin/zsh
 . "$(dirname "$0")/_/husky.sh"
 
 yarn lint-staged
diff --git a/plugins/openapi-router/package.json b/plugins/openapi-router/package.json
index 695a7bfc4d..dfc8b85441 100644
--- a/plugins/openapi-router/package.json
+++ b/plugins/openapi-router/package.json
@@ -24,7 +24,8 @@
     "postpack": "backstage-cli package postpack"
   },
   "devDependencies": {
-    "@backstage/cli": "workspace:^"
+    "@backstage/cli": "workspace:^",
+    "expect-type": "^0.15.0"
   },
   "files": [
     "dist"
diff --git a/plugins/openapi-router/src/types/immutable.ts b/plugins/openapi-router/src/types/immutable.ts
index dec20105cf..7cba014e0a 100644
--- a/plugins/openapi-router/src/types/immutable.ts
+++ b/plugins/openapi-router/src/types/immutable.ts
@@ -18,6 +18,7 @@ import type {
   OpenAPIObject,
   ReferenceObject,
   RequestBodyObject,
+  ParameterObject,
 } from 'openapi3-ts';
 
 /**
@@ -68,3 +69,33 @@ export type ImmutableContentObject = ImmutableObject<ContentObject>;
  * @public
  */
 export type ImmutableRequestBodyObject = ImmutableObject<RequestBodyObject>;
+
+export type ImmutableParameterObject = ImmutableObject<ParameterObject>;
+
+export interface HeaderObject extends ParameterObject {
+  in: 'header';
+  style: 'simple';
+}
+
+export type ImmutableHeaderObject = ImmutableObject<HeaderObject>;
+
+export interface CookieObject extends ParameterObject {
+  in: 'cookie';
+  style: 'form';
+}
+
+export type ImmutableCookieObject = ImmutableObject<CookieObject>;
+
+export interface QueryObject extends ParameterObject {
+  in: 'query';
+  style: 'form' | 'deepObject' | 'pipeDelimited' | 'spaceDelimited';
+}
+
+export type ImmutableQueryObject = ImmutableObject<QueryObject>;
+
+export interface PathObject extends ParameterObject {
+  in: 'path';
+  style: 'simple' | 'label' | 'matrix';
+}
+
+export type ImmutablePathObject = ImmutableObject<PathObject>;
diff --git a/plugins/openapi-router/src/types/params.ts b/plugins/openapi-router/src/types/params.ts
new file mode 100644
index 0000000000..3e06e266dd
--- /dev/null
+++ b/plugins/openapi-router/src/types/params.ts
@@ -0,0 +1,96 @@
+/*
+ * Copyright 2023 The Backstage Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import {
+  ImmutableHeaderObject,
+  ImmutableParameterObject,
+  ImmutableReferenceObject,
+} from './immutable';
+import {
+  ComponentRef,
+  ComponentTypes,
+  DocOperation,
+  DocPathTemplate,
+  PathTemplate,
+  RequiredDoc,
+  TuplifyUnion,
+} from './common';
+import spec from '../schema/petstore';
+import { ParameterLocation } from 'openapi3-ts';
+
+export type ResolveDocParameter<
+  Doc extends RequiredDoc,
+  Path extends Extract<keyof Doc['paths'], string>,
+  Method extends keyof Doc['paths'][Path],
+  Parameter extends keyof Doc['paths'][Path][Method]['parameters'],
+> = DocOperation<
+  Doc,
+  Path,
+  Method
+>['parameters'][Parameter] extends ImmutableReferenceObject
+  ? 'parameters' extends ComponentTypes<Doc>
+    ? ComponentRef<
+        Doc,
+        'parameters',
+        DocOperation<Doc, Path, Method>['parameter'][Parameter]
+      >
+    : never
+  : DocOperation<Doc, Path, Method>['parameters'][Parameter];
+
+export type DocParameter<
+  Doc extends RequiredDoc,
+  Path extends Extract<keyof Doc['paths'], string>,
+  Method extends keyof Doc['paths'][Path],
+  Parameter extends keyof Doc['paths'][Path][Method]['parameters'],
+> = ResolveDocParameter<
+  Doc,
+  Path,
+  Method,
+  Parameter
+> extends ImmutableParameterObject
+  ? ResolveDocParameter<Doc, Path, Method, Parameter>
+  : never;
+
+type KeysMatching<T extends any[], V> = {
+  [K in keyof T]-?: T[K] extends V ? K : never;
+}[keyof T];
+/**
+ * @public
+ */
+export type ConvertAll<T, R extends ReadonlyArray<unknown> = []> = T extends [
+  infer First extends JSONSchema7,
+  ...infer Rest,
+]
+  ? ConvertAll<Rest, [...R, FromSchema<First>]>
+  : R;
+/**
+ * @public
+ */
+export type DocParameters<
+  Doc extends RequiredDoc,
+  Path extends DocPathTemplate<Doc>,
+  Method extends keyof Doc['paths'][Path],
+> = TuplifyUnion<>;
+
+export type HeaderSchema<
+  Doc extends RequiredDoc,
+  Path extends PathTemplate<Extract<keyof Doc['paths'], string>>,
+  Method extends keyof Doc['paths'][Path],
+> = KeysMatching<DocParameters<Doc, Path, Method>, ImmutableHeaderObject>;
+
+type keys = HeaderSchema<typeof spec, '/pets', 'get'>;
+
+type match = KeysMatching<[1, 2, 3], 1>;
diff --git a/yarn.lock b/yarn.lock
index 7601b411e7..1442f4d64e 100644
--- a/yarn.lock
+++ b/yarn.lock
@@ -7802,6 +7802,7 @@ __metadata:
     "@backstage/cli": "workspace:^"
     "@types/express": ^4.17.6
     "@types/express-serve-static-core": ^4.17.33
+    expect-type: ^0.15.0
     express: ^4.17.1
     express-promise-router: ^4.1.0
     json-schema-to-ts: ^2.6.2
@@ -24090,6 +24091,13 @@ __metadata:
   languageName: node
   linkType: hard
 
+"expect-type@npm:^0.15.0":
+  version: 0.15.0
+  resolution: "expect-type@npm:0.15.0"
+  checksum: f5d3733bb593d9f7cf302b393e34b19389fb7022d72963815e9a847a9517b65201faef733dd9006bed9e200486d77204fd958c8d29ef58b466bed2da076fc0ba
+  languageName: node
+  linkType: hard
+
 "expect@npm:^28.0.0":
   version: 28.1.3
   resolution: "expect@npm:28.1.3"

From 056fda5106663a4e0fb251931eed05d97f5bcafb Mon Sep 17 00:00:00 2001
From: Aramis Sennyey <sennyeya@amazon.com>
Date: Fri, 3 Mar 2023 14:43:33 -0500
Subject: [PATCH 29/61] Add support for path + query variables.

Signed-off-by: Aramis Sennyey <sennyeya@amazon.com>
---
 plugins/catalog-backend/openapi.yaml          |  68 +++++-----
 .../src/service/schema/openapi.ts             |  83 ++++++------
 plugins/openapi-router/src/types/common.ts    |  33 +++++
 plugins/openapi-router/src/types/express.ts   |   9 +-
 plugins/openapi-router/src/types/immutable.ts |   9 +-
 plugins/openapi-router/src/types/params.ts    | 123 ++++++++++++------
 6 files changed, 202 insertions(+), 123 deletions(-)

diff --git a/plugins/catalog-backend/openapi.yaml b/plugins/catalog-backend/openapi.yaml
index 5028f4d556..07d1bc9ca5 100644
--- a/plugins/catalog-backend/openapi.yaml
+++ b/plugins/catalog-backend/openapi.yaml
@@ -16,6 +16,30 @@ components:
   examples: {}
   headers: {}
   parameters:
+    kind:
+      name: kind
+      in: path
+      required: true
+      schema:
+        type: string
+    namespace:
+      name: namespace
+      in: path
+      required: true
+      schema:
+        type: string
+    name:
+      name: name
+      in: path
+      required: true
+      schema:
+        type: string
+    uid:
+      name: uid
+      in: path
+      required: true
+      schema:
+        type: string
     cursor:
       name: cursor
       in: query
@@ -634,11 +658,7 @@ paths:
         - {}
         - JWT: []
       parameters:
-        - in: path
-          name: uid
-          required: true
-          schema:
-            type: string
+        - $ref: '#/components/parameters/uid'
     delete:
       operationId: DeleteEntityByUid
       responses:
@@ -667,21 +687,9 @@ paths:
         - {}
         - JWT: []
       parameters:
-        - in: path
-          name: kind
-          required: true
-          schema:
-            type: string
-        - in: path
-          name: namespace
-          required: true
-          schema:
-            type: string
-        - in: path
-          name: name
-          required: true
-          schema:
-            type: string
+        - $ref: '#/components/parameters/kind'
+        - $ref: '#/components/parameters/namespace'
+        - $ref: '#/components/parameters/name'
   /entities/by-name/{kind}/{namespace}/{name}/ancestry:
     get:
       operationId: GetEntityAncestryByName
@@ -696,21 +704,9 @@ paths:
         - {}
         - JWT: []
       parameters:
-        - in: path
-          name: kind
-          required: true
-          schema:
-            type: string
-        - in: path
-          name: namespace
-          required: true
-          schema:
-            type: string
-        - in: path
-          name: name
-          required: true
-          schema:
-            type: string
+        - $ref: '#/components/parameters/kind'
+        - $ref: '#/components/parameters/namespace'
+        - $ref: '#/components/parameters/name'
   /entities/by-refs:
     post:
       operationId: GetEntitiesByRefs
@@ -835,7 +831,7 @@ paths:
           name: dryRun
           required: false
           schema:
-            type: boolean
+            type: string
       requestBody:
         required: true
         content:
diff --git a/plugins/catalog-backend/src/service/schema/openapi.ts b/plugins/catalog-backend/src/service/schema/openapi.ts
index ce725a59de..6ec4f25527 100644
--- a/plugins/catalog-backend/src/service/schema/openapi.ts
+++ b/plugins/catalog-backend/src/service/schema/openapi.ts
@@ -35,6 +35,38 @@ export default {
     examples: {},
     headers: {},
     parameters: {
+      kind: {
+        name: 'kind',
+        in: 'path',
+        required: true,
+        schema: {
+          type: 'string',
+        },
+      },
+      namespace: {
+        name: 'namespace',
+        in: 'path',
+        required: true,
+        schema: {
+          type: 'string',
+        },
+      },
+      name: {
+        name: 'name',
+        in: 'path',
+        required: true,
+        schema: {
+          type: 'string',
+        },
+      },
+      uid: {
+        name: 'uid',
+        in: 'path',
+        required: true,
+        schema: {
+          type: 'string',
+        },
+      },
       cursor: {
         name: 'cursor',
         in: 'query',
@@ -769,12 +801,7 @@ export default {
         ],
         parameters: [
           {
-            in: 'path',
-            name: 'uid',
-            required: true,
-            schema: {
-              type: 'string',
-            },
+            $ref: '#/components/parameters/uid',
           },
         ],
       },
@@ -826,28 +853,13 @@ export default {
         ],
         parameters: [
           {
-            in: 'path',
-            name: 'kind',
-            required: true,
-            schema: {
-              type: 'string',
-            },
+            $ref: '#/components/parameters/kind',
           },
           {
-            in: 'path',
-            name: 'namespace',
-            required: true,
-            schema: {
-              type: 'string',
-            },
+            $ref: '#/components/parameters/namespace',
           },
           {
-            in: 'path',
-            name: 'name',
-            required: true,
-            schema: {
-              type: 'string',
-            },
+            $ref: '#/components/parameters/name',
           },
         ],
       },
@@ -875,28 +887,13 @@ export default {
         ],
         parameters: [
           {
-            in: 'path',
-            name: 'kind',
-            required: true,
-            schema: {
-              type: 'string',
-            },
+            $ref: '#/components/parameters/kind',
           },
           {
-            in: 'path',
-            name: 'namespace',
-            required: true,
-            schema: {
-              type: 'string',
-            },
+            $ref: '#/components/parameters/namespace',
           },
           {
-            in: 'path',
-            name: 'name',
-            required: true,
-            schema: {
-              type: 'string',
-            },
+            $ref: '#/components/parameters/name',
           },
         ],
       },
@@ -1104,7 +1101,7 @@ export default {
             name: 'dryRun',
             required: false,
             schema: {
-              type: 'boolean',
+              type: 'string',
             },
           },
         ],
diff --git a/plugins/openapi-router/src/types/common.ts b/plugins/openapi-router/src/types/common.ts
index ac1fc29b84..d1171257ed 100644
--- a/plugins/openapi-router/src/types/common.ts
+++ b/plugins/openapi-router/src/types/common.ts
@@ -230,3 +230,36 @@ export type UnknownIfNever<P> = [P] extends [never] ? unknown : P;
  * @public
  */
 export type ToTypeSafe<T> = UnknownIfNever<ConvertAll<TuplifyUnion<T>>[number]>;
+
+type DiscriminateUnion<T, K extends keyof T, V extends T[K]> = Extract<
+  T,
+  Record<K, V>
+>;
+
+export type MapDiscriminatedUnion<
+  T extends Record<K, string>,
+  K extends keyof T,
+> = {
+  [V in T[K]]: DiscriminateUnion<T, K, V>;
+};
+
+export type PickOptionalKeys<T extends { [key: string]: any }> = {
+  [K in keyof T]: true extends T[K]['required'] ? never : K;
+}[keyof T];
+
+export type PickRequiredKeys<T extends { [key: string]: any }> = {
+  [K in keyof T]: true extends T[K]['required'] ? K : never;
+}[keyof T];
+
+export type OptionalMap<T extends { [key: string]: any }> = {
+  [P in Exclude<PickOptionalKeys<T>, undefined>]?: NonNullable<T[P]>;
+};
+
+export type RequiredMap<T extends { [key: string]: any }> = {
+  [P in Exclude<PickRequiredKeys<T>, undefined>]: NonNullable<T[P]>;
+};
+
+export type FullMap<T extends { [key: string]: any }> = RequiredMap<T> &
+  OptionalMap<T>;
+
+export type Filter<T, U> = T extends U ? T : never;
diff --git a/plugins/openapi-router/src/types/express.ts b/plugins/openapi-router/src/types/express.ts
index 4a6fcdedcb..87b91c6c7c 100644
--- a/plugins/openapi-router/src/types/express.ts
+++ b/plugins/openapi-router/src/types/express.ts
@@ -15,6 +15,7 @@
  */
 import core from 'express-serve-static-core';
 import { DocPathTemplate, MethodAwareDocPath, RequiredDoc } from './common';
+import { PathSchema, QuerySchema } from './params';
 import { RequestBodyToJsonSchema } from './requests';
 import { ResponseBodyToJsonSchema } from './responses';
 
@@ -35,10 +36,10 @@ export type DocRequestHandler<
   Path extends DocPathTemplate<Doc>,
   Method extends keyof Doc['paths'][Path],
 > = core.RequestHandler<
-  core.ParamsDictionary,
+  PathSchema<Doc, Path, Method>,
   ResponseBodyToJsonSchema<Doc, Path, Method>,
   RequestBodyToJsonSchema<Doc, Path, Method>,
-  ParsedQs,
+  QuerySchema<Doc, Path, Method>,
   Record<string, string>
 >;
 
@@ -51,10 +52,10 @@ export type DocRequestHandlerParams<
   Path extends DocPathTemplate<Doc>,
   Method extends keyof Doc['paths'][Path],
 > = core.RequestHandlerParams<
-  core.ParamsDictionary,
+  PathSchema<Doc, Path, Method>,
   ResponseBodyToJsonSchema<Doc, Path, Method>,
   RequestBodyToJsonSchema<Doc, Path, Method>,
-  ParsedQs,
+  QuerySchema<Doc, Path, Method>,
   Record<string, string>
 >;
 
diff --git a/plugins/openapi-router/src/types/immutable.ts b/plugins/openapi-router/src/types/immutable.ts
index 7cba014e0a..dc6e20c827 100644
--- a/plugins/openapi-router/src/types/immutable.ts
+++ b/plugins/openapi-router/src/types/immutable.ts
@@ -19,6 +19,7 @@ import type {
   ReferenceObject,
   RequestBodyObject,
   ParameterObject,
+  SchemaObject,
 } from 'openapi3-ts';
 
 /**
@@ -81,21 +82,23 @@ export type ImmutableHeaderObject = ImmutableObject<HeaderObject>;
 
 export interface CookieObject extends ParameterObject {
   in: 'cookie';
-  style: 'form';
+  style?: 'form';
 }
 
 export type ImmutableCookieObject = ImmutableObject<CookieObject>;
 
 export interface QueryObject extends ParameterObject {
   in: 'query';
-  style: 'form' | 'deepObject' | 'pipeDelimited' | 'spaceDelimited';
+  style?: 'form' | 'deepObject' | 'pipeDelimited' | 'spaceDelimited';
 }
 
 export type ImmutableQueryObject = ImmutableObject<QueryObject>;
 
 export interface PathObject extends ParameterObject {
   in: 'path';
-  style: 'simple' | 'label' | 'matrix';
+  style?: 'simple' | 'label' | 'matrix';
 }
 
 export type ImmutablePathObject = ImmutableObject<PathObject>;
+
+export type ImmutableSchemaObject = ImmutableObject<SchemaObject>;
diff --git a/plugins/openapi-router/src/types/params.ts b/plugins/openapi-router/src/types/params.ts
index 3e06e266dd..9af1fa6eaa 100644
--- a/plugins/openapi-router/src/types/params.ts
+++ b/plugins/openapi-router/src/types/params.ts
@@ -15,23 +15,30 @@
  */
 
 import {
+  ImmutableCookieObject,
   ImmutableHeaderObject,
   ImmutableParameterObject,
+  ImmutablePathObject,
+  ImmutableQueryObject,
   ImmutableReferenceObject,
+  ImmutableSchemaObject,
 } from './immutable';
 import {
   ComponentRef,
   ComponentTypes,
   DocOperation,
-  DocPathTemplate,
+  DocPath,
+  DocPathMethod,
+  Filter,
+  FullMap,
+  MapDiscriminatedUnion,
   PathTemplate,
   RequiredDoc,
-  TuplifyUnion,
 } from './common';
+import { FromSchema, JSONSchema7 } from 'json-schema-to-ts';
 import spec from '../schema/petstore';
-import { ParameterLocation } from 'openapi3-ts';
 
-export type ResolveDocParameter<
+export type DocParameter<
   Doc extends RequiredDoc,
   Path extends Extract<keyof Doc['paths'], string>,
   Method extends keyof Doc['paths'][Path],
@@ -45,52 +52,94 @@ export type ResolveDocParameter<
     ? ComponentRef<
         Doc,
         'parameters',
-        DocOperation<Doc, Path, Method>['parameter'][Parameter]
+        DocOperation<Doc, Path, Method>['parameters'][Parameter]
       >
     : never
   : DocOperation<Doc, Path, Method>['parameters'][Parameter];
 
-export type DocParameter<
-  Doc extends RequiredDoc,
-  Path extends Extract<keyof Doc['paths'], string>,
-  Method extends keyof Doc['paths'][Path],
-  Parameter extends keyof Doc['paths'][Path][Method]['parameters'],
-> = ResolveDocParameter<
-  Doc,
-  Path,
-  Method,
-  Parameter
-> extends ImmutableParameterObject
-  ? ResolveDocParameter<Doc, Path, Method, Parameter>
-  : never;
-
-type KeysMatching<T extends any[], V> = {
-  [K in keyof T]-?: T[K] extends V ? K : never;
-}[keyof T];
-/**
- * @public
- */
-export type ConvertAll<T, R extends ReadonlyArray<unknown> = []> = T extends [
-  infer First extends JSONSchema7,
-  ...infer Rest,
-]
-  ? ConvertAll<Rest, [...R, FromSchema<First>]>
-  : R;
 /**
  * @public
  */
 export type DocParameters<
   Doc extends RequiredDoc,
-  Path extends DocPathTemplate<Doc>,
+  Path extends Extract<keyof Doc['paths'], string>,
   Method extends keyof Doc['paths'][Path],
-> = TuplifyUnion<>;
+> = DocOperation<Doc, Path, Method>['parameters'] extends ReadonlyArray<any>
+  ? {
+      [Index in keyof DocOperation<
+        Doc,
+        Path,
+        Method
+      >['parameters']]: DocParameter<Doc, Path, Method, Index>;
+    }
+  : never;
+
+export type ResolveDocParameterSchema<
+  Doc extends RequiredDoc,
+  Schema extends ImmutableParameterObject['schema'],
+> = Schema extends ImmutableReferenceObject
+  ? 'parameters' extends ComponentTypes<Doc>
+    ? ComponentRef<Doc, 'parameters', Schema>
+    : never
+  : Schema;
+
+export type ParameterSchema<
+  Doc extends RequiredDoc,
+  Schema extends ImmutableParameterObject['schema'],
+> = ResolveDocParameterSchema<Doc, Schema> extends infer R
+  ? R extends ImmutableSchemaObject
+    ? R extends JSONSchema7
+      ? FromSchema<R>
+      : never
+    : never
+  : never;
+
+type MapToSchema<
+  Doc extends RequiredDoc,
+  T extends Record<string, ImmutableParameterObject>,
+> = {
+  [V in keyof T]: NonNullable<T[V]> extends ImmutableParameterObject
+    ? ParameterSchema<Doc, NonNullable<T[V]>['schema']>
+    : never;
+};
+
+export type ParametersSchema<
+  Doc extends RequiredDoc,
+  Path extends Extract<keyof Doc['paths'], string>,
+  Method extends keyof Doc['paths'][Path],
+  FilterType extends ImmutableParameterObject,
+> = number extends keyof DocParameters<Doc, Path, Method>
+  ? MapToSchema<
+      Doc,
+      FullMap<
+        MapDiscriminatedUnion<
+          Filter<DocParameters<Doc, Path, Method>[number], FilterType>,
+          'name'
+        >
+      >
+    >
+  : never;
 
 export type HeaderSchema<
   Doc extends RequiredDoc,
   Path extends PathTemplate<Extract<keyof Doc['paths'], string>>,
-  Method extends keyof Doc['paths'][Path],
-> = KeysMatching<DocParameters<Doc, Path, Method>, ImmutableHeaderObject>;
+  Method extends DocPathMethod<Doc, Path>,
+> = ParametersSchema<Doc, DocPath<Doc, Path>, Method, ImmutableHeaderObject>;
 
-type keys = HeaderSchema<typeof spec, '/pets', 'get'>;
+export type CookieSchema<
+  Doc extends RequiredDoc,
+  Path extends PathTemplate<Extract<keyof Doc['paths'], string>>,
+  Method extends DocPathMethod<Doc, Path>,
+> = ParametersSchema<Doc, DocPath<Doc, Path>, Method, ImmutableCookieObject>;
 
-type match = KeysMatching<[1, 2, 3], 1>;
+export type PathSchema<
+  Doc extends RequiredDoc,
+  Path extends PathTemplate<Extract<keyof Doc['paths'], string>>,
+  Method extends DocPathMethod<Doc, Path>,
+> = ParametersSchema<Doc, DocPath<Doc, Path>, Method, ImmutablePathObject>;
+
+export type QuerySchema<
+  Doc extends RequiredDoc,
+  Path extends PathTemplate<Extract<keyof Doc['paths'], string>>,
+  Method extends DocPathMethod<Doc, Path>,
+> = ParametersSchema<Doc, DocPath<Doc, Path>, Method, ImmutableQueryObject>;

From 5cfd99d12acbc472ddba821e529fc3e5033cc2de Mon Sep 17 00:00:00 2001
From: Aramis Sennyey <sennyeya@amazon.com>
Date: Fri, 3 Mar 2023 15:28:57 -0500
Subject: [PATCH 30/61] Fix API report.

Signed-off-by: Aramis Sennyey <sennyeya@amazon.com>
---
 plugins/openapi-router/api-report.md          | 237 +++++++++++++++++-
 plugins/openapi-router/src/example.ts         |   2 +-
 plugins/openapi-router/src/types/common.ts    |  30 ++-
 plugins/openapi-router/src/types/immutable.ts |  30 +++
 plugins/openapi-router/src/types/index.ts     |   1 +
 plugins/openapi-router/src/types/params.ts    |  30 ++-
 6 files changed, 318 insertions(+), 12 deletions(-)

diff --git a/plugins/openapi-router/api-report.md b/plugins/openapi-router/api-report.md
index 5c09d0432d..28a32cd4af 100644
--- a/plugins/openapi-router/api-report.md
+++ b/plugins/openapi-router/api-report.md
@@ -8,10 +8,12 @@ import core from 'express-serve-static-core';
 import { FromSchema } from 'json-schema-to-ts';
 import { JSONSchema7 } from 'json-schema-to-ts';
 import type { OpenAPIObject } from 'openapi3-ts';
+import type { ParameterObject } from 'openapi3-ts';
 import type { ReferenceObject } from 'openapi3-ts';
 import type { RequestBodyObject } from 'openapi3-ts';
 import type { ResponseObject } from 'openapi3-ts';
 import { Router } from 'express';
+import type { SchemaObject } from 'openapi3-ts';
 
 // @public
 export interface ApiRouter<Doc extends RequiredDoc> extends Router {
@@ -62,6 +64,27 @@ export type ConvertAll<T, R extends ReadonlyArray<unknown> = []> = T extends [
   ? ConvertAll<Rest, [...R, FromSchema<First>]>
   : R;
 
+// @public (undocumented)
+export interface CookieObject extends ParameterObject {
+  // (undocumented)
+  in: 'cookie';
+  // (undocumented)
+  style?: 'form';
+}
+
+// @public (undocumented)
+export type CookieSchema<
+  Doc extends RequiredDoc,
+  Path extends PathTemplate<Extract<keyof Doc['paths'], string>>,
+  Method extends DocPathMethod<Doc, Path>,
+> = ParametersSchema<Doc, DocPath<Doc, Path>, Method, ImmutableCookieObject>;
+
+// @public (undocumented)
+export type DiscriminateUnion<T, K extends keyof T, V extends T[K]> = Extract<
+  T,
+  Record<K, V>
+>;
+
 // @public (undocumented)
 export type DocOperation<
   Doc extends RequiredDoc,
@@ -69,6 +92,41 @@ export type DocOperation<
   Method extends keyof Doc['paths'][Path],
 > = Doc['paths'][Path][Method];
 
+// @public (undocumented)
+export type DocParameter<
+  Doc extends RequiredDoc,
+  Path extends Extract<keyof Doc['paths'], string>,
+  Method extends keyof Doc['paths'][Path],
+  Parameter extends keyof Doc['paths'][Path][Method]['parameters'],
+> = DocOperation<
+  Doc,
+  Path,
+  Method
+>['parameters'][Parameter] extends ImmutableReferenceObject
+  ? 'parameters' extends ComponentTypes<Doc>
+    ? ComponentRef<
+        Doc,
+        'parameters',
+        DocOperation<Doc, Path, Method>['parameters'][Parameter]
+      >
+    : never
+  : DocOperation<Doc, Path, Method>['parameters'][Parameter];
+
+// @public (undocumented)
+export type DocParameters<
+  Doc extends RequiredDoc,
+  Path extends Extract<keyof Doc['paths'], string>,
+  Method extends keyof Doc['paths'][Path],
+> = DocOperation<Doc, Path, Method>['parameters'] extends ReadonlyArray<any>
+  ? {
+      [Index in keyof DocOperation<
+        Doc,
+        Path,
+        Method
+      >['parameters']]: DocParameter<Doc, Path, Method, Index>;
+    }
+  : never;
+
 // @public
 export type DocPath<
   Doc extends PathDoc,
@@ -97,10 +155,10 @@ export type DocRequestHandler<
   Path extends DocPathTemplate<Doc>,
   Method extends keyof Doc['paths'][Path],
 > = core.RequestHandler<
-  core.ParamsDictionary,
+  PathSchema<Doc, Path, Method>,
   ResponseBodyToJsonSchema<Doc, Path, Method>,
   RequestBodyToJsonSchema<Doc, Path, Method>,
-  ParsedQs,
+  QuerySchema<Doc, Path, Method>,
   Record<string, string>
 >;
 
@@ -110,10 +168,10 @@ export type DocRequestHandlerParams<
   Path extends DocPathTemplate<Doc>,
   Method extends keyof Doc['paths'][Path],
 > = core.RequestHandlerParams<
-  core.ParamsDictionary,
+  PathSchema<Doc, Path, Method>,
   ResponseBodyToJsonSchema<Doc, Path, Method>,
   RequestBodyToJsonSchema<Doc, Path, Method>,
-  ParsedQs,
+  QuerySchema<Doc, Path, Method>,
   Record<string, string>
 >;
 
@@ -143,6 +201,31 @@ export interface DocRequestMatcher<
   ): T;
 }
 
+// @public (undocumented)
+export type Filter<T, U> = T extends U ? T : never;
+
+// @public (undocumented)
+export type FullMap<
+  T extends {
+    [key: string]: any;
+  },
+> = RequiredMap<T> & OptionalMap<T>;
+
+// @public (undocumented)
+export interface HeaderObject extends ParameterObject {
+  // (undocumented)
+  in: 'header';
+  // (undocumented)
+  style: 'simple';
+}
+
+// @public (undocumented)
+export type HeaderSchema<
+  Doc extends RequiredDoc,
+  Path extends PathTemplate<Extract<keyof Doc['paths'], string>>,
+  Method extends DocPathMethod<Doc, Path>,
+> = ParametersSchema<Doc, DocPath<Doc, Path>, Method, ImmutableHeaderObject>;
+
 // @public
 export type Immutable<T> = T extends
   | Function
@@ -163,6 +246,12 @@ export type Immutable<T> = T extends
 // @public (undocumented)
 export type ImmutableContentObject = ImmutableObject<ContentObject>;
 
+// @public (undocumented)
+export type ImmutableCookieObject = ImmutableObject<CookieObject>;
+
+// @public (undocumented)
+export type ImmutableHeaderObject = ImmutableObject<HeaderObject>;
+
 // @public (undocumented)
 export type ImmutableObject<T> = {
   readonly [K in keyof T]: Immutable<T[K]>;
@@ -171,12 +260,24 @@ export type ImmutableObject<T> = {
 // @public (undocumented)
 export type ImmutableOpenAPIObject = ImmutableObject<OpenAPIObject>;
 
+// @public (undocumented)
+export type ImmutableParameterObject = ImmutableObject<ParameterObject>;
+
+// @public (undocumented)
+export type ImmutablePathObject = ImmutableObject<PathObject>;
+
+// @public (undocumented)
+export type ImmutableQueryObject = ImmutableObject<QueryObject>;
+
 // @public (undocumented)
 export type ImmutableReferenceObject = ImmutableObject<ReferenceObject>;
 
 // @public (undocumented)
 export type ImmutableRequestBodyObject = ImmutableObject<RequestBodyObject>;
 
+// @public (undocumented)
+export type ImmutableSchemaObject = ImmutableObject<SchemaObject>;
+
 // @public (undocumented)
 export type LastOf<T> = UnionToIntersection<
   T extends any ? () => T : never
@@ -184,6 +285,24 @@ export type LastOf<T> = UnionToIntersection<
   ? R
   : never;
 
+// @public (undocumented)
+export type MapDiscriminatedUnion<
+  T extends Record<K, string>,
+  K extends keyof T,
+> = {
+  [V in T[K]]: DiscriminateUnion<T, K, V>;
+};
+
+// @public (undocumented)
+export type MapToSchema<
+  Doc extends RequiredDoc,
+  T extends Record<string, ImmutableParameterObject>,
+> = {
+  [V in keyof T]: NonNullable<T[V]> extends ImmutableParameterObject
+    ? ParameterSchema<Doc, NonNullable<T[V]>['schema']>
+    : never;
+};
+
 // @public (undocumented)
 export type MethodAwareDocPath<
   Doc extends PathDoc,
@@ -210,6 +329,45 @@ export type ObjectWithContentSchema<
   ? SchemaRef<Doc, Object['content']['application/json']['schema']>
   : never;
 
+// @public (undocumented)
+export type OptionalMap<
+  T extends {
+    [key: string]: any;
+  },
+> = {
+  [P in Exclude<PickOptionalKeys<T>, undefined>]?: NonNullable<T[P]>;
+};
+
+// @public (undocumented)
+export type ParameterSchema<
+  Doc extends RequiredDoc,
+  Schema extends ImmutableParameterObject['schema'],
+> = ResolveDocParameterSchema<Doc, Schema> extends infer R
+  ? R extends ImmutableSchemaObject
+    ? R extends JSONSchema7
+      ? FromSchema<R>
+      : never
+    : never
+  : never;
+
+// @public (undocumented)
+export type ParametersSchema<
+  Doc extends RequiredDoc,
+  Path extends Extract<keyof Doc['paths'], string>,
+  Method extends keyof Doc['paths'][Path],
+  FilterType extends ImmutableParameterObject,
+> = number extends keyof DocParameters<Doc, Path, Method>
+  ? MapToSchema<
+      Doc,
+      FullMap<
+        MapDiscriminatedUnion<
+          Filter<DocParameters<Doc, Path, Method>[number], FilterType>,
+          'name'
+        >
+      >
+    >
+  : never;
+
 // @public
 export interface ParsedQs {
   // (undocumented)
@@ -219,15 +377,63 @@ export interface ParsedQs {
 // @public (undocumented)
 export type PathDoc = Pick<ImmutableOpenAPIObject, 'paths'>;
 
+// @public (undocumented)
+export interface PathObject extends ParameterObject {
+  // (undocumented)
+  in: 'path';
+  // (undocumented)
+  style?: 'simple' | 'label' | 'matrix';
+}
+
+// @public (undocumented)
+export type PathSchema<
+  Doc extends RequiredDoc,
+  Path extends PathTemplate<Extract<keyof Doc['paths'], string>>,
+  Method extends DocPathMethod<Doc, Path>,
+> = ParametersSchema<Doc, DocPath<Doc, Path>, Method, ImmutablePathObject>;
+
 // @public
 export type PathTemplate<Path extends string> =
-  Path extends `${infer Prefix}{${string}}${infer Suffix}`
-    ? `${Prefix}${string}${PathTemplate<Suffix>}`
+  Path extends `${infer Prefix}{${infer PathName}}${infer Suffix}`
+    ? `${Prefix}:${PathName}${PathTemplate<Suffix>}`
     : Path;
 
+// @public (undocumented)
+export type PickOptionalKeys<
+  T extends {
+    [key: string]: any;
+  },
+> = {
+  [K in keyof T]: true extends T[K]['required'] ? never : K;
+}[keyof T];
+
+// @public (undocumented)
+export type PickRequiredKeys<
+  T extends {
+    [key: string]: any;
+  },
+> = {
+  [K in keyof T]: true extends T[K]['required'] ? K : never;
+}[keyof T];
+
 // @public (undocumented)
 export type Push<T extends any[], V> = [...T, V];
 
+// @public (undocumented)
+export interface QueryObject extends ParameterObject {
+  // (undocumented)
+  in: 'query';
+  // (undocumented)
+  style?: 'form' | 'deepObject' | 'pipeDelimited' | 'spaceDelimited';
+}
+
+// @public (undocumented)
+export type QuerySchema<
+  Doc extends RequiredDoc,
+  Path extends PathTemplate<Extract<keyof Doc['paths'], string>>,
+  Method extends DocPathMethod<Doc, Path>,
+> = ParametersSchema<Doc, DocPath<Doc, Path>, Method, ImmutableQueryObject>;
+
 // @public (undocumented)
 export type RequestBody<
   Doc extends RequiredDoc,
@@ -270,6 +476,25 @@ export type RequestBodyToJsonSchema<
 // @public
 export type RequiredDoc = Pick<ImmutableOpenAPIObject, 'paths' | 'components'>;
 
+// @public (undocumented)
+export type RequiredMap<
+  T extends {
+    [key: string]: any;
+  },
+> = {
+  [P in Exclude<PickRequiredKeys<T>, undefined>]: NonNullable<T[P]>;
+};
+
+// @public (undocumented)
+export type ResolveDocParameterSchema<
+  Doc extends RequiredDoc,
+  Schema extends ImmutableParameterObject['schema'],
+> = Schema extends ImmutableReferenceObject
+  ? 'parameters' extends ComponentTypes<Doc>
+    ? ComponentRef<Doc, 'parameters', Schema>
+    : never
+  : Schema;
+
 // @public (undocumented)
 type Response_2<
   Doc extends RequiredDoc,
diff --git a/plugins/openapi-router/src/example.ts b/plugins/openapi-router/src/example.ts
index af9871993a..9aa3047b28 100644
--- a/plugins/openapi-router/src/example.ts
+++ b/plugins/openapi-router/src/example.ts
@@ -26,7 +26,7 @@ export async function createRouter(
   console.log(options);
   const router = Router() as ApiRouter<typeof doc>;
 
-  router.get('/pets/:uid', (_, res) => {
+  router.get('/pets/:petId', (_, res) => {
     res.json({
       id: 1,
       name: 'test',
diff --git a/plugins/openapi-router/src/types/common.ts b/plugins/openapi-router/src/types/common.ts
index d1171257ed..50ed6e03cd 100644
--- a/plugins/openapi-router/src/types/common.ts
+++ b/plugins/openapi-router/src/types/common.ts
@@ -58,8 +58,8 @@ export type ValueOf<T> = T[keyof T];
  * @public
  */
 export type PathTemplate<Path extends string> =
-  Path extends `${infer Prefix}{${string}}${infer Suffix}`
-    ? `${Prefix}${string}${PathTemplate<Suffix>}`
+  Path extends `${infer Prefix}{${infer PathName}}${infer Suffix}`
+    ? `${Prefix}:${PathName}${PathTemplate<Suffix>}`
     : Path;
 
 /**
@@ -231,11 +231,17 @@ export type UnknownIfNever<P> = [P] extends [never] ? unknown : P;
  */
 export type ToTypeSafe<T> = UnknownIfNever<ConvertAll<TuplifyUnion<T>>[number]>;
 
-type DiscriminateUnion<T, K extends keyof T, V extends T[K]> = Extract<
+/**
+ * @public
+ */
+export type DiscriminateUnion<T, K extends keyof T, V extends T[K]> = Extract<
   T,
   Record<K, V>
 >;
 
+/**
+ * @public
+ */
 export type MapDiscriminatedUnion<
   T extends Record<K, string>,
   K extends keyof T,
@@ -243,23 +249,41 @@ export type MapDiscriminatedUnion<
   [V in T[K]]: DiscriminateUnion<T, K, V>;
 };
 
+/**
+ * @public
+ */
 export type PickOptionalKeys<T extends { [key: string]: any }> = {
   [K in keyof T]: true extends T[K]['required'] ? never : K;
 }[keyof T];
 
+/**
+ * @public
+ */
 export type PickRequiredKeys<T extends { [key: string]: any }> = {
   [K in keyof T]: true extends T[K]['required'] ? K : never;
 }[keyof T];
 
+/**
+ * @public
+ */
 export type OptionalMap<T extends { [key: string]: any }> = {
   [P in Exclude<PickOptionalKeys<T>, undefined>]?: NonNullable<T[P]>;
 };
 
+/**
+ * @public
+ */
 export type RequiredMap<T extends { [key: string]: any }> = {
   [P in Exclude<PickRequiredKeys<T>, undefined>]: NonNullable<T[P]>;
 };
 
+/**
+ * @public
+ */
 export type FullMap<T extends { [key: string]: any }> = RequiredMap<T> &
   OptionalMap<T>;
 
+/**
+ * @public
+ */
 export type Filter<T, U> = T extends U ? T : never;
diff --git a/plugins/openapi-router/src/types/immutable.ts b/plugins/openapi-router/src/types/immutable.ts
index dc6e20c827..880a081ba0 100644
--- a/plugins/openapi-router/src/types/immutable.ts
+++ b/plugins/openapi-router/src/types/immutable.ts
@@ -71,34 +71,64 @@ export type ImmutableContentObject = ImmutableObject<ContentObject>;
  */
 export type ImmutableRequestBodyObject = ImmutableObject<RequestBodyObject>;
 
+/**
+ * @public
+ */
 export type ImmutableParameterObject = ImmutableObject<ParameterObject>;
 
+/**
+ * @public
+ */
 export interface HeaderObject extends ParameterObject {
   in: 'header';
   style: 'simple';
 }
 
+/**
+ * @public
+ */
 export type ImmutableHeaderObject = ImmutableObject<HeaderObject>;
 
+/**
+ * @public
+ */
 export interface CookieObject extends ParameterObject {
   in: 'cookie';
   style?: 'form';
 }
 
+/**
+ * @public
+ */
 export type ImmutableCookieObject = ImmutableObject<CookieObject>;
 
+/**
+ * @public
+ */
 export interface QueryObject extends ParameterObject {
   in: 'query';
   style?: 'form' | 'deepObject' | 'pipeDelimited' | 'spaceDelimited';
 }
 
+/**
+ * @public
+ */
 export type ImmutableQueryObject = ImmutableObject<QueryObject>;
 
+/**
+ * @public
+ */
 export interface PathObject extends ParameterObject {
   in: 'path';
   style?: 'simple' | 'label' | 'matrix';
 }
 
+/**
+ * @public
+ */
 export type ImmutablePathObject = ImmutableObject<PathObject>;
 
+/**
+ * @public
+ */
 export type ImmutableSchemaObject = ImmutableObject<SchemaObject>;
diff --git a/plugins/openapi-router/src/types/index.ts b/plugins/openapi-router/src/types/index.ts
index 1a1f5265bf..e656e1967c 100644
--- a/plugins/openapi-router/src/types/index.ts
+++ b/plugins/openapi-router/src/types/index.ts
@@ -18,3 +18,4 @@ export * from './express';
 export * from './requests';
 export * from './responses';
 export * from './immutable';
+export * from './params';
diff --git a/plugins/openapi-router/src/types/params.ts b/plugins/openapi-router/src/types/params.ts
index 9af1fa6eaa..dce743e6e8 100644
--- a/plugins/openapi-router/src/types/params.ts
+++ b/plugins/openapi-router/src/types/params.ts
@@ -36,8 +36,10 @@ import {
   RequiredDoc,
 } from './common';
 import { FromSchema, JSONSchema7 } from 'json-schema-to-ts';
-import spec from '../schema/petstore';
 
+/**
+ * @public
+ */
 export type DocParameter<
   Doc extends RequiredDoc,
   Path extends Extract<keyof Doc['paths'], string>,
@@ -74,6 +76,9 @@ export type DocParameters<
     }
   : never;
 
+/**
+ * @public
+ */
 export type ResolveDocParameterSchema<
   Doc extends RequiredDoc,
   Schema extends ImmutableParameterObject['schema'],
@@ -83,6 +88,9 @@ export type ResolveDocParameterSchema<
     : never
   : Schema;
 
+/**
+ * @public
+ */
 export type ParameterSchema<
   Doc extends RequiredDoc,
   Schema extends ImmutableParameterObject['schema'],
@@ -94,7 +102,10 @@ export type ParameterSchema<
     : never
   : never;
 
-type MapToSchema<
+/**
+ * @public
+ */
+export type MapToSchema<
   Doc extends RequiredDoc,
   T extends Record<string, ImmutableParameterObject>,
 > = {
@@ -103,6 +114,9 @@ type MapToSchema<
     : never;
 };
 
+/**
+ * @public
+ */
 export type ParametersSchema<
   Doc extends RequiredDoc,
   Path extends Extract<keyof Doc['paths'], string>,
@@ -120,24 +134,36 @@ export type ParametersSchema<
     >
   : never;
 
+/**
+ * @public
+ */
 export type HeaderSchema<
   Doc extends RequiredDoc,
   Path extends PathTemplate<Extract<keyof Doc['paths'], string>>,
   Method extends DocPathMethod<Doc, Path>,
 > = ParametersSchema<Doc, DocPath<Doc, Path>, Method, ImmutableHeaderObject>;
 
+/**
+ * @public
+ */
 export type CookieSchema<
   Doc extends RequiredDoc,
   Path extends PathTemplate<Extract<keyof Doc['paths'], string>>,
   Method extends DocPathMethod<Doc, Path>,
 > = ParametersSchema<Doc, DocPath<Doc, Path>, Method, ImmutableCookieObject>;
 
+/**
+ * @public
+ */
 export type PathSchema<
   Doc extends RequiredDoc,
   Path extends PathTemplate<Extract<keyof Doc['paths'], string>>,
   Method extends DocPathMethod<Doc, Path>,
 > = ParametersSchema<Doc, DocPath<Doc, Path>, Method, ImmutablePathObject>;
 
+/**
+ * @public
+ */
 export type QuerySchema<
   Doc extends RequiredDoc,
   Path extends PathTemplate<Extract<keyof Doc['paths'], string>>,

From 87f40d36f8c7282a60ef827d6762c8f33705f186 Mon Sep 17 00:00:00 2001
From: Aramis Sennyey <sennyeya@amazon.com>
Date: Fri, 3 Mar 2023 15:51:27 -0500
Subject: [PATCH 31/61] Fix immutability with responses.

Signed-off-by: Aramis Sennyey <sennyeya@amazon.com>
---
 plugins/openapi-router/src/types/immutable.ts | 6 ++++++
 plugins/openapi-router/src/types/responses.ts | 8 ++++----
 2 files changed, 10 insertions(+), 4 deletions(-)

diff --git a/plugins/openapi-router/src/types/immutable.ts b/plugins/openapi-router/src/types/immutable.ts
index 880a081ba0..5056512054 100644
--- a/plugins/openapi-router/src/types/immutable.ts
+++ b/plugins/openapi-router/src/types/immutable.ts
@@ -20,6 +20,7 @@ import type {
   RequestBodyObject,
   ParameterObject,
   SchemaObject,
+  ResponseObject,
 } from 'openapi3-ts';
 
 /**
@@ -71,6 +72,11 @@ export type ImmutableContentObject = ImmutableObject<ContentObject>;
  */
 export type ImmutableRequestBodyObject = ImmutableObject<RequestBodyObject>;
 
+/**
+ * @public
+ */
+export type ImmutableResponseObject = ImmutableObject<ResponseObject>;
+
 /**
  * @public
  */
diff --git a/plugins/openapi-router/src/types/responses.ts b/plugins/openapi-router/src/types/responses.ts
index 50a8289dd6..c623b44333 100644
--- a/plugins/openapi-router/src/types/responses.ts
+++ b/plugins/openapi-router/src/types/responses.ts
@@ -18,7 +18,6 @@
  * Pulled from https://github.com/varanauskas/oatx.
  */
 
-import type { ReferenceObject, ResponseObject } from 'openapi3-ts';
 import type {
   ComponentRef,
   ComponentTypes,
@@ -32,6 +31,7 @@ import type {
   ToTypeSafe,
   ValueOf,
 } from './common';
+import { ImmutableReferenceObject, ImmutableResponseObject } from './immutable';
 
 /**
  * @public
@@ -45,7 +45,7 @@ export type Response<
   Doc,
   Path,
   Method
->['responses'][StatusCode] extends ReferenceObject
+>['responses'][StatusCode] extends ImmutableReferenceObject
   ? 'responses' extends ComponentTypes<Doc>
     ? ComponentRef<
         Doc,
@@ -76,7 +76,7 @@ export type Responses<
  */
 export type ResponseSchema<
   Doc extends RequiredDoc,
-  Object extends ResponseObject,
+  Object extends ImmutableResponseObject,
 > = ObjectWithContentSchema<Doc, Object>;
 
 /**
@@ -91,7 +91,7 @@ export type ResponseSchemas<
     Doc,
     DocPath<Doc, Path>,
     Method
-  >[StatusCode] extends ResponseObject
+  >[StatusCode] extends ImmutableResponseObject
     ? ResponseSchema<
         Doc,
         Responses<Doc, DocPath<Doc, Path>, Method>[StatusCode]

From 08ea0c1861c0a9e22b488bceb160e2bcf299f0f9 Mon Sep 17 00:00:00 2001
From: Aramis Sennyey <sennyeya@amazon.com>
Date: Mon, 6 Mar 2023 10:17:53 -0500
Subject: [PATCH 32/61] Update spec, fix by-refs issue, remove unused
 dependency.

Signed-off-by: Aramis Sennyey <sennyeya@amazon.com>
---
 .husky/pre-commit                             |  2 +-
 plugins/catalog-backend/openapi.yaml          | 24 +++++-----
 plugins/catalog-backend/package.json          |  3 +-
 .../src/service/schema/openapi.ts             | 31 ++++++------
 plugins/openapi-router/README.md              |  4 +-
 plugins/openapi-router/package.json           |  6 +--
 plugins/openapi-router/src/run.ts             | 33 -------------
 .../openapi-router/src/standaloneServer.ts    | 48 -------------------
 yarn.lock                                     | 43 ++++++++---------
 9 files changed, 55 insertions(+), 139 deletions(-)
 delete mode 100644 plugins/openapi-router/src/run.ts
 delete mode 100644 plugins/openapi-router/src/standaloneServer.ts

diff --git a/.husky/pre-commit b/.husky/pre-commit
index 8862d8db03..d2ae35e84b 100755
--- a/.husky/pre-commit
+++ b/.husky/pre-commit
@@ -1,4 +1,4 @@
-#!/bin/zsh
+#!/bin/sh
 . "$(dirname "$0")/_/husky.sh"
 
 yarn lint-staged
diff --git a/plugins/catalog-backend/openapi.yaml b/plugins/catalog-backend/openapi.yaml
index 07d1bc9ca5..ecab6c7272 100644
--- a/plugins/catalog-backend/openapi.yaml
+++ b/plugins/catalog-backend/openapi.yaml
@@ -731,9 +731,18 @@ paths:
         content:
           application/json:
             schema:
-              type: array
-              items:
-                type: string
+              type: object
+              required:
+                - entityRefs
+              properties:
+                entityRefs:
+                  type: array
+                  items:
+                    type: string
+                fields:
+                  type: array
+                  items:
+                    type: string
   /entities/by-query:
     get:
       operationId: GetEntitiesByQuery
@@ -768,15 +777,6 @@ paths:
               type: string
           explode: false
           style: form
-
-      requestBody:
-        required: true
-        content:
-          application/json:
-            schema:
-              type: array
-              items:
-                type: string
   /entity-facets:
     get:
       operationId: GetEntityFacets
diff --git a/plugins/catalog-backend/package.json b/plugins/catalog-backend/package.json
index ef6fdd8029..2d77c724c5 100644
--- a/plugins/catalog-backend/package.json
+++ b/plugins/catalog-backend/package.json
@@ -46,6 +46,7 @@
   },
   "dependencies": {
     "@backstage/backend-common": "workspace:^",
+    "@backstage/backend-openapi-utils": "workspace:^",
     "@backstage/backend-plugin-api": "workspace:^",
     "@backstage/catalog-client": "workspace:^",
     "@backstage/catalog-model": "workspace:^",
@@ -54,7 +55,6 @@
     "@backstage/integration": "workspace:^",
     "@backstage/plugin-catalog-common": "workspace:^",
     "@backstage/plugin-catalog-node": "workspace:^",
-    "@backstage/plugin-openapi-router": "workspace:^",
     "@backstage/plugin-permission-common": "workspace:^",
     "@backstage/plugin-permission-node": "workspace:^",
     "@backstage/plugin-scaffolder-common": "workspace:^",
@@ -71,7 +71,6 @@
     "fs-extra": "10.1.0",
     "git-url-parse": "^13.0.0",
     "glob": "^7.1.6",
-    "js-yaml": "^4.1.0",
     "knex": "^2.0.0",
     "lodash": "^4.17.21",
     "luxon": "^3.0.0",
diff --git a/plugins/catalog-backend/src/service/schema/openapi.ts b/plugins/catalog-backend/src/service/schema/openapi.ts
index 6ec4f25527..e14410cd30 100644
--- a/plugins/catalog-backend/src/service/schema/openapi.ts
+++ b/plugins/catalog-backend/src/service/schema/openapi.ts
@@ -934,9 +934,21 @@ export default {
           content: {
             'application/json': {
               schema: {
-                type: 'array',
-                items: {
-                  type: 'string',
+                type: 'object',
+                required: ['entityRefs'],
+                properties: {
+                  entityRefs: {
+                    type: 'array',
+                    items: {
+                      type: 'string',
+                    },
+                  },
+                  fields: {
+                    type: 'array',
+                    items: {
+                      type: 'string',
+                    },
+                  },
                 },
               },
             },
@@ -1003,19 +1015,6 @@ export default {
             style: 'form',
           },
         ],
-        requestBody: {
-          required: true,
-          content: {
-            'application/json': {
-              schema: {
-                type: 'array',
-                items: {
-                  type: 'string',
-                },
-              },
-            },
-          },
-        },
       },
     },
     '/entity-facets': {
diff --git a/plugins/openapi-router/README.md b/plugins/openapi-router/README.md
index ad45dae773..1cb8575cb9 100644
--- a/plugins/openapi-router/README.md
+++ b/plugins/openapi-router/README.md
@@ -8,7 +8,7 @@ This package is meant to provide a typed Express router for an OpenAPI spec. Spe
 
 ### Configuration
 
-In your plugin's `schema/openapi`,
+In your plugin's `schema/openapi.ts`,
 
 ```ts
 export default {
@@ -34,7 +34,7 @@ export function createRouter(){
 1. OpenAPI definitions must be converted to Typescript files
    From [#32063](https://github.com/microsoft/TypeScript/issues/32063), we cannot import JSON `as const`. If we could, this would allow us to force all specs to be JSON and then just import from a spec.
 2. `as const` makes all fields `readonly`
-   To ensure a good DX of
+   To ensure a good DX of using a simple imported JSON spec, we want to remove any type issues between `readonly` arrays and mutable arrays. Typescript does not allow them to be compared, so converting all imports from the `openapi3-ts` library to `readonly` is important.
 
 ```tsx
 ...
diff --git a/plugins/openapi-router/package.json b/plugins/openapi-router/package.json
index dfc8b85441..df0e92bdc1 100644
--- a/plugins/openapi-router/package.json
+++ b/plugins/openapi-router/package.json
@@ -1,6 +1,6 @@
 {
-  "name": "@backstage/plugin-openapi-router",
-  "description": "OpenAPI router with type completions.",
+  "name": "@backstage/backend-openapi-utils",
+  "description": "OpenAPI typescript support.",
   "version": "0.0.0",
   "main": "src/index.ts",
   "types": "src/index.ts",
@@ -12,7 +12,7 @@
     "types": "dist/index.d.ts"
   },
   "backstage": {
-    "role": "backend-plugin"
+    "role": "node-library"
   },
   "scripts": {
     "start": "backstage-cli package start",
diff --git a/plugins/openapi-router/src/run.ts b/plugins/openapi-router/src/run.ts
deleted file mode 100644
index 9a14d0e57d..0000000000
--- a/plugins/openapi-router/src/run.ts
+++ /dev/null
@@ -1,33 +0,0 @@
-/*
- * Copyright 2020 The Backstage Authors
- *
- * Licensed under the Apache License, Version 2.0 (the "License");
- * you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- *     http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
- */
-
-import yn from 'yn';
-import { getRootLogger } from '@backstage/backend-common';
-import { startStandaloneServer } from './standaloneServer';
-
-const port = process.env.PLUGIN_PORT ? Number(process.env.PLUGIN_PORT) : 3004;
-const enableCors = yn(process.env.PLUGIN_CORS, { default: false });
-const logger = getRootLogger();
-
-startStandaloneServer({ port, enableCors, logger }).catch(err => {
-  logger.error(err);
-  process.exit(1);
-});
-
-process.on('SIGINT', () => {
-  logger.info('CTRL+C pressed; exiting.');
-  process.exit(0);
-});
diff --git a/plugins/openapi-router/src/standaloneServer.ts b/plugins/openapi-router/src/standaloneServer.ts
deleted file mode 100644
index f7c2ec2c61..0000000000
--- a/plugins/openapi-router/src/standaloneServer.ts
+++ /dev/null
@@ -1,48 +0,0 @@
-/*
- * Copyright 2020 The Backstage Authors
- *
- * Licensed under the Apache License, Version 2.0 (the "License");
- * you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- *     http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
- */
-
-import { Server } from 'http';
-import { Logger } from 'winston';
-import { createServiceBuilder } from '@backstage/backend-common';
-import { createRouter } from './example';
-
-export interface ServerOptions {
-  port: number;
-  enableCors: boolean;
-  logger: Logger;
-}
-
-export async function startStandaloneServer(
-  options: ServerOptions,
-): Promise<Server> {
-  const logger = options.logger.child({ service: 'app-backend' });
-  logger.debug('Starting application server...');
-  const router = await createRouter({
-    logger,
-    appPackageName: 'example-app',
-  });
-
-  const service = createServiceBuilder(module)
-    .setPort(options.port)
-    .addRouter('', router);
-
-  return await service.start().catch(err => {
-    logger.error(err);
-    process.exit(1);
-  });
-}
-
-module.hot?.accept();
diff --git a/yarn.lock b/yarn.lock
index 1442f4d64e..e0fb52c28e 100644
--- a/yarn.lock
+++ b/yarn.lock
@@ -3929,6 +3929,26 @@ __metadata:
   languageName: unknown
   linkType: soft
 
+"@backstage/backend-openapi-utils@workspace:^, @backstage/backend-openapi-utils@workspace:plugins/openapi-router":
+  version: 0.0.0-use.local
+  resolution: "@backstage/backend-openapi-utils@workspace:plugins/openapi-router"
+  dependencies:
+    "@backstage/backend-common": "workspace:^"
+    "@backstage/cli": "workspace:^"
+    "@types/express": ^4.17.6
+    "@types/express-serve-static-core": ^4.17.33
+    expect-type: ^0.15.0
+    express: ^4.17.1
+    express-promise-router: ^4.1.0
+    json-schema-to-ts: ^2.6.2
+    openapi-types: ^12.1.0
+    openapi3-ts: ^3.1.2
+    ts-node: ^10.9.1
+    winston: ^3.8.2
+    yn: ^4.0.0
+  languageName: unknown
+  linkType: soft
+
 "@backstage/backend-plugin-api@workspace:^, @backstage/backend-plugin-api@workspace:packages/backend-plugin-api":
   version: 0.0.0-use.local
   resolution: "@backstage/backend-plugin-api@workspace:packages/backend-plugin-api"
@@ -5691,6 +5711,7 @@ __metadata:
   resolution: "@backstage/plugin-catalog-backend@workspace:plugins/catalog-backend"
   dependencies:
     "@backstage/backend-common": "workspace:^"
+    "@backstage/backend-openapi-utils": "workspace:^"
     "@backstage/backend-plugin-api": "workspace:^"
     "@backstage/backend-test-utils": "workspace:^"
     "@backstage/catalog-client": "workspace:^"
@@ -5701,7 +5722,6 @@ __metadata:
     "@backstage/integration": "workspace:^"
     "@backstage/plugin-catalog-common": "workspace:^"
     "@backstage/plugin-catalog-node": "workspace:^"
-    "@backstage/plugin-openapi-router": "workspace:^"
     "@backstage/plugin-permission-common": "workspace:^"
     "@backstage/plugin-permission-node": "workspace:^"
     "@backstage/plugin-scaffolder-common": "workspace:^"
@@ -5725,7 +5745,6 @@ __metadata:
     fs-extra: 10.1.0
     git-url-parse: ^13.0.0
     glob: ^7.1.6
-    js-yaml: ^4.1.0
     knex: ^2.0.0
     lodash: ^4.17.21
     luxon: ^3.0.0
@@ -7794,26 +7813,6 @@ __metadata:
   languageName: unknown
   linkType: soft
 
-"@backstage/plugin-openapi-router@workspace:^, @backstage/plugin-openapi-router@workspace:plugins/openapi-router":
-  version: 0.0.0-use.local
-  resolution: "@backstage/plugin-openapi-router@workspace:plugins/openapi-router"
-  dependencies:
-    "@backstage/backend-common": "workspace:^"
-    "@backstage/cli": "workspace:^"
-    "@types/express": ^4.17.6
-    "@types/express-serve-static-core": ^4.17.33
-    expect-type: ^0.15.0
-    express: ^4.17.1
-    express-promise-router: ^4.1.0
-    json-schema-to-ts: ^2.6.2
-    openapi-types: ^12.1.0
-    openapi3-ts: ^3.1.2
-    ts-node: ^10.9.1
-    winston: ^3.8.2
-    yn: ^4.0.0
-  languageName: unknown
-  linkType: soft
-
 "@backstage/plugin-org-react@workspace:plugins/org-react":
   version: 0.0.0-use.local
   resolution: "@backstage/plugin-org-react@workspace:plugins/org-react"

From c6c01b5e2eb9f22f34024b1357e49a2812c54b8b Mon Sep 17 00:00:00 2001
From: Aramis Sennyey <sennyeya@amazon.com>
Date: Mon, 6 Mar 2023 10:28:09 -0500
Subject: [PATCH 33/61] Update import.

Signed-off-by: Aramis Sennyey <sennyeya@amazon.com>
---
 plugins/catalog-backend/src/service/createRouter.ts | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/plugins/catalog-backend/src/service/createRouter.ts b/plugins/catalog-backend/src/service/createRouter.ts
index 2f83723281..db2f569d54 100644
--- a/plugins/catalog-backend/src/service/createRouter.ts
+++ b/plugins/catalog-backend/src/service/createRouter.ts
@@ -50,7 +50,7 @@ import {
   locationInput,
   validateRequestBody,
 } from './util';
-import { ApiRouter } from '@backstage/plugin-openapi-router';
+import { ApiRouter } from '@backstage/backend-openapi-utils';
 import spec from './schema/openapi';
 
 /**

From 978b09f273e3ff75efc73c5abe7247cfd44a90fa Mon Sep 17 00:00:00 2001
From: Aramis Sennyey <sennyeya@amazon.com>
Date: Mon, 6 Mar 2023 11:18:42 -0500
Subject: [PATCH 34/61] Fix naming and API report.

Signed-off-by: Aramis Sennyey <sennyeya@amazon.com>
---
 .../{openapi-router => openapi-utils}/.eslintrc.js    |  0
 plugins/{openapi-router => openapi-utils}/README.md   |  0
 .../{openapi-router => openapi-utils}/api-report.md   | 11 +++++++----
 .../{openapi-router => openapi-utils}/package.json    |  0
 .../{openapi-router => openapi-utils}/src/example.ts  |  0
 .../{openapi-router => openapi-utils}/src/index.ts    |  0
 .../{openapi-router => openapi-utils}/src/router.ts   |  0
 .../src/schema/petstore.ts                            |  0
 .../src/setupTests.ts                                 |  0
 .../src/types/common.ts                               |  0
 .../src/types/express.ts                              |  0
 .../src/types/immutable.ts                            |  0
 .../src/types/index.ts                                |  0
 .../src/types/params.ts                               |  0
 .../src/types/requests.ts                             |  0
 .../src/types/responses.ts                            |  0
 yarn.lock                                             |  4 ++--
 17 files changed, 9 insertions(+), 6 deletions(-)
 rename plugins/{openapi-router => openapi-utils}/.eslintrc.js (100%)
 rename plugins/{openapi-router => openapi-utils}/README.md (100%)
 rename plugins/{openapi-router => openapi-utils}/api-report.md (98%)
 rename plugins/{openapi-router => openapi-utils}/package.json (100%)
 rename plugins/{openapi-router => openapi-utils}/src/example.ts (100%)
 rename plugins/{openapi-router => openapi-utils}/src/index.ts (100%)
 rename plugins/{openapi-router => openapi-utils}/src/router.ts (100%)
 rename plugins/{openapi-router => openapi-utils}/src/schema/petstore.ts (100%)
 rename plugins/{openapi-router => openapi-utils}/src/setupTests.ts (100%)
 rename plugins/{openapi-router => openapi-utils}/src/types/common.ts (100%)
 rename plugins/{openapi-router => openapi-utils}/src/types/express.ts (100%)
 rename plugins/{openapi-router => openapi-utils}/src/types/immutable.ts (100%)
 rename plugins/{openapi-router => openapi-utils}/src/types/index.ts (100%)
 rename plugins/{openapi-router => openapi-utils}/src/types/params.ts (100%)
 rename plugins/{openapi-router => openapi-utils}/src/types/requests.ts (100%)
 rename plugins/{openapi-router => openapi-utils}/src/types/responses.ts (100%)

diff --git a/plugins/openapi-router/.eslintrc.js b/plugins/openapi-utils/.eslintrc.js
similarity index 100%
rename from plugins/openapi-router/.eslintrc.js
rename to plugins/openapi-utils/.eslintrc.js
diff --git a/plugins/openapi-router/README.md b/plugins/openapi-utils/README.md
similarity index 100%
rename from plugins/openapi-router/README.md
rename to plugins/openapi-utils/README.md
diff --git a/plugins/openapi-router/api-report.md b/plugins/openapi-utils/api-report.md
similarity index 98%
rename from plugins/openapi-router/api-report.md
rename to plugins/openapi-utils/api-report.md
index 28a32cd4af..a51fd8e4f7 100644
--- a/plugins/openapi-router/api-report.md
+++ b/plugins/openapi-utils/api-report.md
@@ -1,4 +1,4 @@
-## API Report File for "@backstage/plugin-openapi-router"
+## API Report File for "@backstage/backend-openapi-utils"
 
 > Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.com/).
 
@@ -275,6 +275,9 @@ export type ImmutableReferenceObject = ImmutableObject<ReferenceObject>;
 // @public (undocumented)
 export type ImmutableRequestBodyObject = ImmutableObject<RequestBodyObject>;
 
+// @public (undocumented)
+export type ImmutableResponseObject = ImmutableObject<ResponseObject>;
+
 // @public (undocumented)
 export type ImmutableSchemaObject = ImmutableObject<SchemaObject>;
 
@@ -505,7 +508,7 @@ type Response_2<
   Doc,
   Path,
   Method
->['responses'][StatusCode] extends ReferenceObject
+>['responses'][StatusCode] extends ImmutableReferenceObject
   ? 'responses' extends ComponentTypes<Doc>
     ? ComponentRef<
         Doc,
@@ -539,7 +542,7 @@ export type Responses<
 // @public (undocumented)
 export type ResponseSchema<
   Doc extends RequiredDoc,
-  Object extends ResponseObject,
+  Object extends ImmutableResponseObject,
 > = ObjectWithContentSchema<Doc, Object>;
 
 // @public (undocumented)
@@ -552,7 +555,7 @@ export type ResponseSchemas<
     Doc,
     DocPath<Doc, Path>,
     Method
-  >[StatusCode] extends ResponseObject
+  >[StatusCode] extends ImmutableResponseObject
     ? ResponseSchema<
         Doc,
         Responses<Doc, DocPath<Doc, Path>, Method>[StatusCode]
diff --git a/plugins/openapi-router/package.json b/plugins/openapi-utils/package.json
similarity index 100%
rename from plugins/openapi-router/package.json
rename to plugins/openapi-utils/package.json
diff --git a/plugins/openapi-router/src/example.ts b/plugins/openapi-utils/src/example.ts
similarity index 100%
rename from plugins/openapi-router/src/example.ts
rename to plugins/openapi-utils/src/example.ts
diff --git a/plugins/openapi-router/src/index.ts b/plugins/openapi-utils/src/index.ts
similarity index 100%
rename from plugins/openapi-router/src/index.ts
rename to plugins/openapi-utils/src/index.ts
diff --git a/plugins/openapi-router/src/router.ts b/plugins/openapi-utils/src/router.ts
similarity index 100%
rename from plugins/openapi-router/src/router.ts
rename to plugins/openapi-utils/src/router.ts
diff --git a/plugins/openapi-router/src/schema/petstore.ts b/plugins/openapi-utils/src/schema/petstore.ts
similarity index 100%
rename from plugins/openapi-router/src/schema/petstore.ts
rename to plugins/openapi-utils/src/schema/petstore.ts
diff --git a/plugins/openapi-router/src/setupTests.ts b/plugins/openapi-utils/src/setupTests.ts
similarity index 100%
rename from plugins/openapi-router/src/setupTests.ts
rename to plugins/openapi-utils/src/setupTests.ts
diff --git a/plugins/openapi-router/src/types/common.ts b/plugins/openapi-utils/src/types/common.ts
similarity index 100%
rename from plugins/openapi-router/src/types/common.ts
rename to plugins/openapi-utils/src/types/common.ts
diff --git a/plugins/openapi-router/src/types/express.ts b/plugins/openapi-utils/src/types/express.ts
similarity index 100%
rename from plugins/openapi-router/src/types/express.ts
rename to plugins/openapi-utils/src/types/express.ts
diff --git a/plugins/openapi-router/src/types/immutable.ts b/plugins/openapi-utils/src/types/immutable.ts
similarity index 100%
rename from plugins/openapi-router/src/types/immutable.ts
rename to plugins/openapi-utils/src/types/immutable.ts
diff --git a/plugins/openapi-router/src/types/index.ts b/plugins/openapi-utils/src/types/index.ts
similarity index 100%
rename from plugins/openapi-router/src/types/index.ts
rename to plugins/openapi-utils/src/types/index.ts
diff --git a/plugins/openapi-router/src/types/params.ts b/plugins/openapi-utils/src/types/params.ts
similarity index 100%
rename from plugins/openapi-router/src/types/params.ts
rename to plugins/openapi-utils/src/types/params.ts
diff --git a/plugins/openapi-router/src/types/requests.ts b/plugins/openapi-utils/src/types/requests.ts
similarity index 100%
rename from plugins/openapi-router/src/types/requests.ts
rename to plugins/openapi-utils/src/types/requests.ts
diff --git a/plugins/openapi-router/src/types/responses.ts b/plugins/openapi-utils/src/types/responses.ts
similarity index 100%
rename from plugins/openapi-router/src/types/responses.ts
rename to plugins/openapi-utils/src/types/responses.ts
diff --git a/yarn.lock b/yarn.lock
index e0fb52c28e..0069effc02 100644
--- a/yarn.lock
+++ b/yarn.lock
@@ -3929,9 +3929,9 @@ __metadata:
   languageName: unknown
   linkType: soft
 
-"@backstage/backend-openapi-utils@workspace:^, @backstage/backend-openapi-utils@workspace:plugins/openapi-router":
+"@backstage/backend-openapi-utils@workspace:^, @backstage/backend-openapi-utils@workspace:plugins/openapi-utils":
   version: 0.0.0-use.local
-  resolution: "@backstage/backend-openapi-utils@workspace:plugins/openapi-router"
+  resolution: "@backstage/backend-openapi-utils@workspace:plugins/openapi-utils"
   dependencies:
     "@backstage/backend-common": "workspace:^"
     "@backstage/cli": "workspace:^"

From 06b016e9b8760536955b5fefee73da45a431328b Mon Sep 17 00:00:00 2001
From: Aramis Sennyey <sennyeya@amazon.com>
Date: Tue, 7 Mar 2023 16:49:01 -0500
Subject: [PATCH 35/61] Add generate and verify commands.

Signed-off-by: Aramis Sennyey <sennyeya@amazon.com>
---
 .github/workflows/ci.yml                      |  3 +
 packages/cli/package.json                     |  1 +
 packages/cli/src/commands/index.ts            | 21 +++++
 packages/cli/src/commands/openapi/generate.ts | 41 +++++++++
 packages/cli/src/commands/openapi/verify.ts   | 91 +++++++++++++++++++
 .../{src/service => }/schema/openapi.ts       |  0
 .../src/service/createRouter.ts               |  2 +-
 yarn.lock                                     |  1 +
 8 files changed, 159 insertions(+), 1 deletion(-)
 create mode 100644 packages/cli/src/commands/openapi/generate.ts
 create mode 100644 packages/cli/src/commands/openapi/verify.ts
 rename plugins/catalog-backend/{src/service => }/schema/openapi.ts (100%)

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index cd67d2742a..4bd7622796 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -92,6 +92,9 @@ jobs:
       - name: verify api reference
         run: node scripts/verify-api-reference.js
 
+      - name: verify openapi yaml <> ts files
+        run: yarn backstage-cli schema:openapi:verify
+
       - name: verify doc links
         run: node scripts/verify-links.js
 
diff --git a/packages/cli/package.json b/packages/cli/package.json
index 5974116843..5e99a3cba0 100644
--- a/packages/cli/package.json
+++ b/packages/cli/package.json
@@ -96,6 +96,7 @@
     "jest-css-modules": "^2.1.0",
     "jest-environment-jsdom": "^29.0.2",
     "jest-runtime": "^29.0.2",
+    "js-yaml": "^4.1.0",
     "json-schema": "^0.4.0",
     "lodash": "^4.17.21",
     "mini-css-extract-plugin": "^2.4.2",
diff --git a/packages/cli/src/commands/index.ts b/packages/cli/src/commands/index.ts
index ba11a53cfd..6c29741060 100644
--- a/packages/cli/src/commands/index.ts
+++ b/packages/cli/src/commands/index.ts
@@ -80,6 +80,13 @@ export function registerRepoCommand(program: Command) {
       lazy(() => import('./repo/list-deprecations').then(m => m.command)),
     );
 
+  command
+    .command('schema:openapi:verify')
+    .description(
+      'Verify that all OpenAPI schemas are valid and have a matching `schemas/openapi.ts` file.',
+    )
+    .action(lazy(() => import('./openapi/verify').then(m => m.bulkCommand)));
+
   command
     .command('test')
     .allowUnknownOption(true) // Allows the command to run, but we still need to parse raw args
@@ -179,6 +186,20 @@ export function registerScriptCommand(program: Command) {
     .command('postpack')
     .description('Restores the changes made by the prepack command')
     .action(lazy(() => import('./pack').then(m => m.post)));
+
+  command
+    .command('schema:openapi:verify')
+    .description(
+      'Verifies that an OpenAPI spec is defined in both an `openapi.yaml` file and a `schema/openapi.ts` file.',
+    )
+    .action(lazy(() => import('./openapi/verify').then(m => m.command)));
+
+  command
+    .command('schema:openapi:generate')
+    .description(
+      'Generates a `schema/openapi.ts` file from an OpenAPI spec defined in `openapi.yaml`.',
+    )
+    .action(lazy(() => import('./openapi/generate').then(m => m.command)));
 }
 
 export function registerMigrateCommand(program: Command) {
diff --git a/packages/cli/src/commands/openapi/generate.ts b/packages/cli/src/commands/openapi/generate.ts
new file mode 100644
index 0000000000..f90f152b09
--- /dev/null
+++ b/packages/cli/src/commands/openapi/generate.ts
@@ -0,0 +1,41 @@
+/*
+ * Copyright 2023 The Backstage Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import fs from 'fs-extra';
+import { paths } from '../../lib/paths';
+import YAML from 'js-yaml';
+
+export async function command() {
+  const openapiPath = paths.resolveTarget('openapi.yaml');
+  if (!(await fs.pathExists(openapiPath))) {
+    console.warn('Could not find openapi.yaml in root of directory.');
+    process.exit(1);
+  }
+  try {
+    const yaml = YAML.load(
+      await fs.readFile(paths.resolveTarget('openapi.yaml'), 'utf8'),
+    );
+
+    // For now, we're not adding a header or linting after pasting.
+    await fs.writeFile(
+      paths.resolveTarget('schema/openapi.ts'),
+      `export default ${JSON.stringify(yaml, null, 2)} as const`,
+    );
+  } catch (err) {
+    console.error(err);
+    process.exit(1);
+  }
+}
diff --git a/packages/cli/src/commands/openapi/verify.ts b/packages/cli/src/commands/openapi/verify.ts
new file mode 100644
index 0000000000..7d3de8e7ee
--- /dev/null
+++ b/packages/cli/src/commands/openapi/verify.ts
@@ -0,0 +1,91 @@
+/*
+ * Copyright 2023 The Backstage Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import fs from 'fs-extra';
+import { paths } from '../../lib/paths';
+import YAML from 'js-yaml';
+import { isEqual } from 'lodash';
+import { join } from 'path';
+import chalk from 'chalk';
+import { relative as relativePath } from 'path';
+import { PackageGraph } from '../../lib/monorepo';
+
+async function verify(directoryPath: string) {
+  const openapiPath = join(directoryPath, 'openapi.yaml');
+  if (!(await fs.pathExists(openapiPath))) {
+    return;
+  }
+  const yaml = YAML.load(await fs.readFile(openapiPath, 'utf8'));
+
+  const schemaPath = join(directoryPath, 'schema/openapi.ts');
+  if (!(await fs.pathExists(schemaPath))) {
+    throw new Error('No `schema/openapi.ts` file found.');
+  }
+  const schema = await import(join(directoryPath, 'schema/openapi'));
+  if (schema.default) {
+    if (!isEqual(schema.default, yaml)) {
+      throw new Error(
+        '`openapi.yaml` and `schema/openapi.ts` do not match. Please run `yarn build:openapi` to generate the `schema/openapi.ts` file from the `openapi.yaml` file.',
+      );
+    }
+  } else {
+    throw new Error('`schemas/openapi.ts` needs to have a default export.');
+  }
+}
+
+export async function command() {
+  try {
+    await verify(paths.resolveTarget('.'));
+  } catch (err) {
+    console.error(chalk.red(err.message));
+    process.exit(1);
+  }
+}
+
+export async function bulkCommand(): Promise<void> {
+  const packages = await PackageGraph.listTargetPackages();
+
+  const resultsList = await Promise.all(
+    packages.map(async pkg => {
+      let resultText = '';
+      try {
+        await verify(pkg.dir);
+      } catch (err) {
+        resultText = err.message;
+      }
+
+      return {
+        relativeDir: relativePath(paths.targetRoot, pkg.dir),
+        resultText,
+      };
+    }),
+  );
+
+  let failed = false;
+  for (const { relativeDir, resultText } of resultsList) {
+    if (resultText) {
+      console.log();
+      console.log(chalk.red(`Lint failed in ${relativeDir}:`));
+      console.log(resultText.trimStart());
+
+      failed = true;
+    }
+  }
+
+  if (failed) {
+    process.exit(1);
+  }
+}
diff --git a/plugins/catalog-backend/src/service/schema/openapi.ts b/plugins/catalog-backend/schema/openapi.ts
similarity index 100%
rename from plugins/catalog-backend/src/service/schema/openapi.ts
rename to plugins/catalog-backend/schema/openapi.ts
diff --git a/plugins/catalog-backend/src/service/createRouter.ts b/plugins/catalog-backend/src/service/createRouter.ts
index db2f569d54..77fe4a24e8 100644
--- a/plugins/catalog-backend/src/service/createRouter.ts
+++ b/plugins/catalog-backend/src/service/createRouter.ts
@@ -51,7 +51,7 @@ import {
   validateRequestBody,
 } from './util';
 import { ApiRouter } from '@backstage/backend-openapi-utils';
-import spec from './schema/openapi';
+import spec from '../../schema/openapi';
 
 /**
  * Options used by {@link createRouter}.
diff --git a/yarn.lock b/yarn.lock
index 0069effc02..78e5acf047 100644
--- a/yarn.lock
+++ b/yarn.lock
@@ -4157,6 +4157,7 @@ __metadata:
     jest-css-modules: ^2.1.0
     jest-environment-jsdom: ^29.0.2
     jest-runtime: ^29.0.2
+    js-yaml: ^4.1.0
     json-schema: ^0.4.0
     lodash: ^4.17.21
     mini-css-extract-plugin: ^2.4.2

From a876e69b20e6666aa5653ad2d3445b8dbe4169fa Mon Sep 17 00:00:00 2001
From: Aramis Sennyey <sennyeya@amazon.com>
Date: Tue, 7 Mar 2023 16:53:23 -0500
Subject: [PATCH 36/61] Add changeset and API report.

Signed-off-by: Aramis Sennyey <sennyeya@amazon.com>
---
 .changeset/fresh-lions-compete.md |  5 +++++
 packages/cli/cli-report.md        | 30 ++++++++++++++++++++++++++++++
 2 files changed, 35 insertions(+)
 create mode 100644 .changeset/fresh-lions-compete.md

diff --git a/.changeset/fresh-lions-compete.md b/.changeset/fresh-lions-compete.md
new file mode 100644
index 0000000000..906ed37665
--- /dev/null
+++ b/.changeset/fresh-lions-compete.md
@@ -0,0 +1,5 @@
+---
+'@backstage/cli': minor
+---
+
+Adding two new commands to support OpenAPI spec writing, `schema:openapi:generate` to generate the Typescript file that `@backstage/backend-openapi-utils` needs for typing and `schema:openapi:verify` to verify that this file exists and matches your `openapi.yaml` file.
diff --git a/packages/cli/cli-report.md b/packages/cli/cli-report.md
index bad849d283..998f2f3665 100644
--- a/packages/cli/cli-report.md
+++ b/packages/cli/cli-report.md
@@ -209,6 +209,8 @@ Commands:
   clean
   prepack
   postpack
+  schema:openapi:verify
+  schema:openapi:generate
   help [command]
 ```
 
@@ -265,6 +267,24 @@ Options:
   -h, --help
 ```
 
+### `backstage-cli package schema:openapi:generate`
+
+```
+Usage: backstage-cli package schema:openapi:generate [options]
+
+Options:
+  -h, --help
+```
+
+### `backstage-cli package schema:openapi:verify`
+
+```
+Usage: backstage-cli package schema:openapi:verify [options]
+
+Options:
+  -h, --help
+```
+
 ### `backstage-cli package start`
 
 ```
@@ -403,6 +423,7 @@ Commands:
   lint [options]
   clean
   list-deprecations [options]
+  schema:openapi:verify
   test [options]
   help [command]
 ```
@@ -449,6 +470,15 @@ Options:
   -h, --help
 ```
 
+### `backstage-cli repo schema:openapi:verify`
+
+```
+Usage: backstage-cli repo schema:openapi:verify [options]
+
+Options:
+  -h, --help
+```
+
 ### `backstage-cli repo test`
 
 ```

From caddd25a8d2e9cb0ddff5521aa7a2d1b6a9ca51b Mon Sep 17 00:00:00 2001
From: Aramis Sennyey <sennyeya@amazon.com>
Date: Tue, 7 Mar 2023 17:00:41 -0500
Subject: [PATCH 37/61] Validate that the file is valid OpenAPI 3.1.

Signed-off-by: Aramis Sennyey <sennyeya@amazon.com>
---
 packages/cli/package.json                   |  1 +
 packages/cli/src/commands/openapi/verify.ts |  3 +
 yarn.lock                                   | 67 +++++++++++++++++++++
 3 files changed, 71 insertions(+)

diff --git a/packages/cli/package.json b/packages/cli/package.json
index 5e99a3cba0..8f166db53d 100644
--- a/packages/cli/package.json
+++ b/packages/cli/package.json
@@ -30,6 +30,7 @@
     "backstage-cli": "bin/backstage-cli"
   },
   "dependencies": {
+    "@apidevtools/swagger-parser": "^10.1.0",
     "@backstage/cli-common": "workspace:^",
     "@backstage/config": "workspace:^",
     "@backstage/config-loader": "workspace:^",
diff --git a/packages/cli/src/commands/openapi/verify.ts b/packages/cli/src/commands/openapi/verify.ts
index 7d3de8e7ee..ac053a1f5e 100644
--- a/packages/cli/src/commands/openapi/verify.ts
+++ b/packages/cli/src/commands/openapi/verify.ts
@@ -22,6 +22,8 @@ import { join } from 'path';
 import chalk from 'chalk';
 import { relative as relativePath } from 'path';
 import { PackageGraph } from '../../lib/monorepo';
+import { cloneDeep } from 'lodash';
+import SwaggerParser from '@apidevtools/swagger-parser';
 
 async function verify(directoryPath: string) {
   const openapiPath = join(directoryPath, 'openapi.yaml');
@@ -29,6 +31,7 @@ async function verify(directoryPath: string) {
     return;
   }
   const yaml = YAML.load(await fs.readFile(openapiPath, 'utf8'));
+  await SwaggerParser.validate(cloneDeep(yaml));
 
   const schemaPath = join(directoryPath, 'schema/openapi.ts');
   if (!(await fs.pathExists(schemaPath))) {
diff --git a/yarn.lock b/yarn.lock
index 78e5acf047..9056881ebb 100644
--- a/yarn.lock
+++ b/yarn.lock
@@ -18,6 +18,17 @@ __metadata:
   languageName: node
   linkType: hard
 
+"@apidevtools/json-schema-ref-parser@npm:9.0.6":
+  version: 9.0.6
+  resolution: "@apidevtools/json-schema-ref-parser@npm:9.0.6"
+  dependencies:
+    "@jsdevtools/ono": ^7.1.3
+    call-me-maybe: ^1.0.1
+    js-yaml: ^3.13.1
+  checksum: c7ff53623ab8a9dd221772a5757fa0b9e5167a5ac3a71c23596634bae6efc85d8efcdebbe17f73ee5c027ea5afc48c705e8a720f02c4909f9a357d8027040b7b
+  languageName: node
+  linkType: hard
+
 "@apidevtools/json-schema-ref-parser@npm:^9.0.6":
   version: 9.1.2
   resolution: "@apidevtools/json-schema-ref-parser@npm:9.1.2"
@@ -30,6 +41,37 @@ __metadata:
   languageName: node
   linkType: hard
 
+"@apidevtools/openapi-schemas@npm:^2.1.0":
+  version: 2.1.0
+  resolution: "@apidevtools/openapi-schemas@npm:2.1.0"
+  checksum: 4a8f64935b9049ef21e41fa4b188f39f6bc3f5291cebd451701db1115451ccb246a739e46cc5ce9ecdec781671431db40db7851acdac84a990a45756e0f32de3
+  languageName: node
+  linkType: hard
+
+"@apidevtools/swagger-methods@npm:^3.0.2":
+  version: 3.0.2
+  resolution: "@apidevtools/swagger-methods@npm:3.0.2"
+  checksum: d06b1ac5c1956613c4c6be695612ef860cd4e962b93a509ca551735a328a856cae1e33399cac1dcbf8333ba22b231746f3586074769ef0e172cf549ec9e7eaae
+  languageName: node
+  linkType: hard
+
+"@apidevtools/swagger-parser@npm:^10.1.0":
+  version: 10.1.0
+  resolution: "@apidevtools/swagger-parser@npm:10.1.0"
+  dependencies:
+    "@apidevtools/json-schema-ref-parser": 9.0.6
+    "@apidevtools/openapi-schemas": ^2.1.0
+    "@apidevtools/swagger-methods": ^3.0.2
+    "@jsdevtools/ono": ^7.1.3
+    ajv: ^8.6.3
+    ajv-draft-04: ^1.0.0
+    call-me-maybe: ^1.0.1
+  peerDependencies:
+    openapi-types: ">=7"
+  checksum: c7c923755bd025ee2cae97e1cfd525538523ba74c341a0ac814c023ffe5e63fc2d997539a8ccf9a0fcec41a2d6337d40cc5735acb991ddcbb415853a241908d1
+  languageName: node
+  linkType: hard
+
 "@apollo/cache-control-types@npm:^1.0.2":
   version: 1.0.2
   resolution: "@apollo/cache-control-types@npm:1.0.2"
@@ -4066,6 +4108,7 @@ __metadata:
   version: 0.0.0-use.local
   resolution: "@backstage/cli@workspace:packages/cli"
   dependencies:
+    "@apidevtools/swagger-parser": ^10.1.0
     "@backstage/backend-common": "workspace:^"
     "@backstage/cli-common": "workspace:^"
     "@backstage/config": "workspace:^"
@@ -18001,6 +18044,18 @@ __metadata:
   languageName: node
   linkType: hard
 
+"ajv-draft-04@npm:^1.0.0":
+  version: 1.0.0
+  resolution: "ajv-draft-04@npm:1.0.0"
+  peerDependencies:
+    ajv: ^8.5.0
+  peerDependenciesMeta:
+    ajv:
+      optional: true
+  checksum: 3f11fa0e7f7359bef6608657f02ab78e9cc62b1fb7bdd860db0d00351b3863a1189c1a23b72466d2d82726cab4eb20725c76f5e7c134a89865e2bfd0e6828137
+  languageName: node
+  linkType: hard
+
 "ajv-formats@npm:^2.1.1":
   version: 2.1.1
   resolution: "ajv-formats@npm:2.1.1"
@@ -18059,6 +18114,18 @@ __metadata:
   languageName: node
   linkType: hard
 
+"ajv@npm:^8.0.0, ajv@npm:^8.10.0, ajv@npm:^8.12.0, ajv@npm:^8.6.3, ajv@npm:^8.8.0":
+  version: 8.12.0
+  resolution: "ajv@npm:8.12.0"
+  dependencies:
+    fast-deep-equal: ^3.1.1
+    json-schema-traverse: ^1.0.0
+    require-from-string: ^2.0.2
+    uri-js: ^4.2.2
+  checksum: 4dc13714e316e67537c8b31bc063f99a1d9d9a497eb4bbd55191ac0dcd5e4985bbb71570352ad6f1e76684fb6d790928f96ba3b2d4fd6e10024be9612fe3f001
+  languageName: node
+  linkType: hard
+
 "ajv@npm:^8.0.0, ajv@npm:^8.10.0, ajv@npm:^8.12.0, ajv@npm:^8.8.0":
   version: 8.12.0
   resolution: "ajv@npm:8.12.0"

From 7e8f8c4d16f681534e3f048821d5258bf5435784 Mon Sep 17 00:00:00 2001
From: Aramis Sennyey <sennyeya@amazon.com>
Date: Tue, 7 Mar 2023 17:12:11 -0500
Subject: [PATCH 38/61] FIx tsc error.

Signed-off-by: Aramis Sennyey <sennyeya@amazon.com>
---
 packages/cli/src/commands/openapi/verify.ts | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/packages/cli/src/commands/openapi/verify.ts b/packages/cli/src/commands/openapi/verify.ts
index ac053a1f5e..923114128c 100644
--- a/packages/cli/src/commands/openapi/verify.ts
+++ b/packages/cli/src/commands/openapi/verify.ts
@@ -23,7 +23,7 @@ import chalk from 'chalk';
 import { relative as relativePath } from 'path';
 import { PackageGraph } from '../../lib/monorepo';
 import { cloneDeep } from 'lodash';
-import SwaggerParser from '@apidevtools/swagger-parser';
+import { validate as validateSpec } from '@apidevtools/swagger-parser';
 
 async function verify(directoryPath: string) {
   const openapiPath = join(directoryPath, 'openapi.yaml');
@@ -31,7 +31,7 @@ async function verify(directoryPath: string) {
     return;
   }
   const yaml = YAML.load(await fs.readFile(openapiPath, 'utf8'));
-  await SwaggerParser.validate(cloneDeep(yaml));
+  await validateSpec(cloneDeep(yaml) as any);
 
   const schemaPath = join(directoryPath, 'schema/openapi.ts');
   if (!(await fs.pathExists(schemaPath))) {

From 258109d41ddf7e46ed75304fe9956b13b83b6f4d Mon Sep 17 00:00:00 2001
From: Aramis Sennyey <sennyeya@amazon.com>
Date: Tue, 7 Mar 2023 17:25:05 -0500
Subject: [PATCH 39/61] Update ci config.

Signed-off-by: Aramis Sennyey <sennyeya@amazon.com>
---
 .github/workflows/ci.yml | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 4bd7622796..d7fb8c3d74 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -92,8 +92,8 @@ jobs:
       - name: verify api reference
         run: node scripts/verify-api-reference.js
 
-      - name: verify openapi yaml <> ts files
-        run: yarn backstage-cli schema:openapi:verify
+      - name: verify openapi.yaml matches schema/openapi.ts files
+        run: yarn backstage-cli repo schema:openapi:verify
 
       - name: verify doc links
         run: node scripts/verify-links.js

From 62fe726fdc50501b7e42f5dfed3da91138b72f26 Mon Sep 17 00:00:00 2001
From: Aramis Sennyey <sennyeya@amazon.com>
Date: Tue, 7 Mar 2023 17:32:51 -0500
Subject: [PATCH 40/61] Add changeset.

Signed-off-by: Aramis Sennyey <sennyeya@amazon.com>
---
 .changeset/tricky-beans-knock.md | 6 ++++++
 1 file changed, 6 insertions(+)
 create mode 100644 .changeset/tricky-beans-knock.md

diff --git a/.changeset/tricky-beans-knock.md b/.changeset/tricky-beans-knock.md
new file mode 100644
index 0000000000..32357d896c
--- /dev/null
+++ b/.changeset/tricky-beans-knock.md
@@ -0,0 +1,6 @@
+---
+'@backstage/plugin-catalog-backend': minor
+'@backstage/backend-openapi-utils': minor
+---
+
+Adding support for typings based on an `openapi.yaml` file.

From be5aca50114921f2b054bac0d9eadd960cda300b Mon Sep 17 00:00:00 2001
From: Aramis Sennyey <sennyeya@amazon.com>
Date: Tue, 7 Mar 2023 17:57:29 -0500
Subject: [PATCH 41/61] Add role checks.

Signed-off-by: Aramis Sennyey <sennyeya@amazon.com>
---
 .changeset/cold-seahorses-greet.md          |  5 +++
 .changeset/tricky-beans-knock.md            |  5 ++-
 packages/cli/src/commands/openapi/verify.ts | 36 +++++++++++++++++----
 3 files changed, 37 insertions(+), 9 deletions(-)
 create mode 100644 .changeset/cold-seahorses-greet.md

diff --git a/.changeset/cold-seahorses-greet.md b/.changeset/cold-seahorses-greet.md
new file mode 100644
index 0000000000..e50cdfd673
--- /dev/null
+++ b/.changeset/cold-seahorses-greet.md
@@ -0,0 +1,5 @@
+---
+'@backstage/plugin-catalog-backend': patch
+---
+
+Update `openapi.yaml` and use `ApiRouter` type from `@backstage/backend-openapi-utils` to handle automatic types from the OpenAPI spec file.
diff --git a/.changeset/tricky-beans-knock.md b/.changeset/tricky-beans-knock.md
index 32357d896c..1bdd95a365 100644
--- a/.changeset/tricky-beans-knock.md
+++ b/.changeset/tricky-beans-knock.md
@@ -1,6 +1,5 @@
 ---
-'@backstage/plugin-catalog-backend': minor
-'@backstage/backend-openapi-utils': minor
+'@backstage/backend-openapi-utils': patch
 ---
 
-Adding support for typings based on an `openapi.yaml` file.
+New plugin! Primary focus is to support types on `Router`s in backend packages. Developers can use the `ApiRouter` from this package in their packages to support a typed experience based on their OpenAPI specs. The `ApiRouter` supports request bodies, response bodies, query parameters and path parameters, as well as full path-based context of the above. This means no more guessing on an endpoint like `req.post('/not-my-route', (req, res)=>{res.send(req.body.badparam)})`. Typescript would catch `/not-my-route`, `req.body.badparam`, `res.send(req.body.badparam)`.
diff --git a/packages/cli/src/commands/openapi/verify.ts b/packages/cli/src/commands/openapi/verify.ts
index 923114128c..f93672aca9 100644
--- a/packages/cli/src/commands/openapi/verify.ts
+++ b/packages/cli/src/commands/openapi/verify.ts
@@ -18,20 +18,43 @@ import fs from 'fs-extra';
 import { paths } from '../../lib/paths';
 import YAML from 'js-yaml';
 import { isEqual } from 'lodash';
-import { join } from 'path';
+import { join, resolve } from 'path';
 import chalk from 'chalk';
 import { relative as relativePath } from 'path';
 import { PackageGraph } from '../../lib/monorepo';
 import { cloneDeep } from 'lodash';
-import { validate as validateSpec } from '@apidevtools/swagger-parser';
+import Parser from '@apidevtools/swagger-parser';
+import { detectRoleFromPackage } from '../../lib/role';
+
+const SUPPORTED_ROLES = [
+  'backend',
+  'backend-plugin',
+  'backend-plugin-module',
+  'node-library',
+];
+
+async function verify(
+  directoryPath: string,
+  { checkRole }: { checkRole: boolean },
+) {
+  if (checkRole) {
+    const role = detectRoleFromPackage(
+      await fs.readJson(resolve(directoryPath, 'package.json')),
+    );
+
+    if (!SUPPORTED_ROLES.some(r => r === role)) {
+      console.log(chalk.red(`Unsupported role ${role}`));
+      process.exit(1);
+    }
+  }
 
-async function verify(directoryPath: string) {
   const openapiPath = join(directoryPath, 'openapi.yaml');
   if (!(await fs.pathExists(openapiPath))) {
     return;
   }
+
   const yaml = YAML.load(await fs.readFile(openapiPath, 'utf8'));
-  await validateSpec(cloneDeep(yaml) as any);
+  await Parser.validate(cloneDeep(yaml) as any);
 
   const schemaPath = join(directoryPath, 'schema/openapi.ts');
   if (!(await fs.pathExists(schemaPath))) {
@@ -51,7 +74,8 @@ async function verify(directoryPath: string) {
 
 export async function command() {
   try {
-    await verify(paths.resolveTarget('.'));
+    await verify(paths.resolveTarget('.'), { checkRole: true });
+    console.log(chalk.green('OpenAPI files are valid.'));
   } catch (err) {
     console.error(chalk.red(err.message));
     process.exit(1);
@@ -65,7 +89,7 @@ export async function bulkCommand(): Promise<void> {
     packages.map(async pkg => {
       let resultText = '';
       try {
-        await verify(pkg.dir);
+        await verify(pkg.dir, { checkRole: false });
       } catch (err) {
         resultText = err.message;
       }

From 4d72efb7727c3575d1eb0d41caa613269dcd6995 Mon Sep 17 00:00:00 2001
From: Aramis Sennyey <sennyeya@amazon.com>
Date: Tue, 7 Mar 2023 18:17:10 -0500
Subject: [PATCH 42/61] Remove generate and verify from next steps.

Signed-off-by: Aramis Sennyey <sennyeya@amazon.com>
---
 plugins/openapi-utils/README.md | 7 +------
 1 file changed, 1 insertion(+), 6 deletions(-)

diff --git a/plugins/openapi-utils/README.md b/plugins/openapi-utils/README.md
index 1cb8575cb9..882b99b698 100644
--- a/plugins/openapi-utils/README.md
+++ b/plugins/openapi-utils/README.md
@@ -46,15 +46,10 @@ we need to type all internals of this package as `Immutable<T>`.
 
 ## Future Work
 
-### Automatic generation of the `schema/openapi` file
-
-Ideally, this would be automatically generated on `openapi.yaml` updates (like a Webpack plugin), but could also be a CLI command.
-
 ### Runtime validation
 
 Using a package like [`express-openapi-validator`](https://www.npmjs.com/package/express-openapi-validator), would allow us to remove [validation of request bodies with `AJV`](https://github.com/backstage/backstage/blob/master/plugins/catalog-backend/src/service/util.ts#L58).
 
 ### PR-time verification.
 
-1. Verify that Typescript file matches the spec file.
-2. Verify that spec file matches the router input/output.
+1. Verify that spec file matches the router input/output.

From 8bdc62ed53c5f4e0f4b0a23ee55e7f1fa320c774 Mon Sep 17 00:00:00 2001
From: Aramis Sennyey <sennyeya@amazon.com>
Date: Tue, 7 Mar 2023 18:21:43 -0500
Subject: [PATCH 43/61] Remove unused dependencies.

Signed-off-by: Aramis Sennyey <sennyeya@amazon.com>
---
 plugins/openapi-utils/package.json | 10 ++--------
 yarn.lock                          | 17 ++---------------
 2 files changed, 4 insertions(+), 23 deletions(-)

diff --git a/plugins/openapi-utils/package.json b/plugins/openapi-utils/package.json
index df0e92bdc1..f813c268da 100644
--- a/plugins/openapi-utils/package.json
+++ b/plugins/openapi-utils/package.json
@@ -24,23 +24,17 @@
     "postpack": "backstage-cli package postpack"
   },
   "devDependencies": {
-    "@backstage/cli": "workspace:^",
-    "expect-type": "^0.15.0"
+    "@backstage/cli": "workspace:^"
   },
   "files": [
     "dist"
   ],
   "dependencies": {
-    "@backstage/backend-common": "workspace:^",
     "@types/express": "^4.17.6",
     "@types/express-serve-static-core": "^4.17.33",
     "express": "^4.17.1",
     "express-promise-router": "^4.1.0",
     "json-schema-to-ts": "^2.6.2",
-    "openapi-types": "^12.1.0",
-    "openapi3-ts": "^3.1.2",
-    "ts-node": "^10.9.1",
-    "winston": "^3.8.2",
-    "yn": "^4.0.0"
+    "openapi3-ts": "^3.1.2"
   }
 }
diff --git a/yarn.lock b/yarn.lock
index 9056881ebb..5fb233c149 100644
--- a/yarn.lock
+++ b/yarn.lock
@@ -3975,19 +3975,13 @@ __metadata:
   version: 0.0.0-use.local
   resolution: "@backstage/backend-openapi-utils@workspace:plugins/openapi-utils"
   dependencies:
-    "@backstage/backend-common": "workspace:^"
     "@backstage/cli": "workspace:^"
     "@types/express": ^4.17.6
     "@types/express-serve-static-core": ^4.17.33
-    expect-type: ^0.15.0
     express: ^4.17.1
     express-promise-router: ^4.1.0
     json-schema-to-ts: ^2.6.2
-    openapi-types: ^12.1.0
     openapi3-ts: ^3.1.2
-    ts-node: ^10.9.1
-    winston: ^3.8.2
-    yn: ^4.0.0
   languageName: unknown
   linkType: soft
 
@@ -24158,13 +24152,6 @@ __metadata:
   languageName: node
   linkType: hard
 
-"expect-type@npm:^0.15.0":
-  version: 0.15.0
-  resolution: "expect-type@npm:0.15.0"
-  checksum: f5d3733bb593d9f7cf302b393e34b19389fb7022d72963815e9a847a9517b65201faef733dd9006bed9e200486d77204fd958c8d29ef58b466bed2da076fc0ba
-  languageName: node
-  linkType: hard
-
 "expect@npm:^28.0.0":
   version: 28.1.3
   resolution: "expect@npm:28.1.3"
@@ -32450,7 +32437,7 @@ __metadata:
   languageName: node
   linkType: hard
 
-"openapi-types@npm:^12.0.0, openapi-types@npm:^12.1.0":
+"openapi-types@npm:^12.0.0":
   version: 12.1.0
   resolution: "openapi-types@npm:12.1.0"
   checksum: d8f3e2bae519aa6bcf2012f4a5592b7283fe928c06f3bdc182776ce637c7ed8d5f9f342724f68c95c9572aefe21ed5e89b18a0295a703da61af5f97bd2aea9a7
@@ -40631,7 +40618,7 @@ __metadata:
   languageName: node
   linkType: hard
 
-"winston@npm:^3.2.1, winston@npm:^3.8.2":
+"winston@npm:^3.2.1":
   version: 3.8.2
   resolution: "winston@npm:3.8.2"
   dependencies:

From 48776ade797c0be94dbe70fc434869b26a56d4ba Mon Sep 17 00:00:00 2001
From: Aramis Sennyey <sennyeya@amazon.com>
Date: Tue, 14 Mar 2023 15:18:58 -0400
Subject: [PATCH 44/61] Fix yarn.lock file.

Signed-off-by: Aramis Sennyey <sennyeya@amazon.com>
---
 yarn.lock | 219 +++++++++---------------------------------------------
 1 file changed, 36 insertions(+), 183 deletions(-)

diff --git a/yarn.lock b/yarn.lock
index 5fb233c149..d40dfd3ea3 100644
--- a/yarn.lock
+++ b/yarn.lock
@@ -729,15 +729,15 @@ __metadata:
   linkType: hard
 
 "@aws-sdk/client-s3@npm:^3.208.0":
-  version: 3.276.0
-  resolution: "@aws-sdk/client-s3@npm:3.276.0"
+  version: 3.282.0
+  resolution: "@aws-sdk/client-s3@npm:3.282.0"
   dependencies:
     "@aws-crypto/sha1-browser": 3.0.0
     "@aws-crypto/sha256-browser": 3.0.0
     "@aws-crypto/sha256-js": 3.0.0
-    "@aws-sdk/client-sts": 3.276.0
-    "@aws-sdk/config-resolver": 3.272.0
-    "@aws-sdk/credential-provider-node": 3.272.0
+    "@aws-sdk/client-sts": 3.282.0
+    "@aws-sdk/config-resolver": 3.282.0
+    "@aws-sdk/credential-provider-node": 3.282.0
     "@aws-sdk/eventstream-serde-browser": 3.272.0
     "@aws-sdk/eventstream-serde-config-resolver": 3.272.0
     "@aws-sdk/eventstream-serde-node": 3.272.0
@@ -786,20 +786,20 @@ __metadata:
     "@aws-sdk/xml-builder": 3.201.0
     fast-xml-parser: 4.1.2
     tslib: ^2.3.1
-  checksum: f7f475b92c0cff800536fb910bb6ffefcee6e650208f1791ea64c95bcbb6c63ef7a55e3f72af44e2e730a53865857ac4b974f00cb7da1e369d742cc95e33f02a
+  checksum: 4f0a1d9ddad89eb71da6f39c210c451461d570d11bc394c6b3d7af139e3ea077bed88fee56fae8318182e7a26464d31119620f191f0d552b51125b9f6ddffe0b
   languageName: node
   linkType: hard
 
 "@aws-sdk/client-sqs@npm:^3.208.0":
-  version: 3.276.0
-  resolution: "@aws-sdk/client-sqs@npm:3.276.0"
+  version: 3.282.0
+  resolution: "@aws-sdk/client-sqs@npm:3.282.0"
   dependencies:
     "@aws-crypto/sha256-browser": 3.0.0
     "@aws-crypto/sha256-js": 3.0.0
-    "@aws-sdk/client-sts": 3.276.0
-    "@aws-sdk/config-resolver": 3.272.0
-    "@aws-sdk/credential-provider-node": 3.272.0
-    "@aws-sdk/fetch-http-handler": 3.272.0
+    "@aws-sdk/client-sts": 3.282.0
+    "@aws-sdk/config-resolver": 3.282.0
+    "@aws-sdk/credential-provider-node": 3.282.0
+    "@aws-sdk/fetch-http-handler": 3.282.0
     "@aws-sdk/hash-node": 3.272.0
     "@aws-sdk/invalid-dependency": 3.272.0
     "@aws-sdk/md5-js": 3.272.0
@@ -832,7 +832,7 @@ __metadata:
     "@aws-sdk/util-utf8": 3.254.0
     fast-xml-parser: 4.1.2
     tslib: ^2.3.1
-  checksum: 88139fde34fa6348e841de13fce5e68b2dfb735c5358c959f9956a8c918048bde8b1ff701e8e701807af5f67f6df129056986b62a7e07096cc7097f3491d36b8
+  checksum: d3a2a2abb27313666aa8c9842c91a098b2570878a9853d59bf07d480669723d77b74ad2ca8e5297dc593d8e76578c78c2634f81e4eed84b84b020b06af04c423
   languageName: node
   linkType: hard
 
@@ -916,94 +916,6 @@ __metadata:
   languageName: node
   linkType: hard
 
-"@aws-sdk/client-sts@npm:3.272.0":
-  version: 3.272.0
-  resolution: "@aws-sdk/client-sts@npm:3.272.0"
-  dependencies:
-    "@aws-crypto/sha256-browser": 3.0.0
-    "@aws-crypto/sha256-js": 3.0.0
-    "@aws-sdk/config-resolver": 3.272.0
-    "@aws-sdk/credential-provider-node": 3.272.0
-    "@aws-sdk/fetch-http-handler": 3.272.0
-    "@aws-sdk/hash-node": 3.272.0
-    "@aws-sdk/invalid-dependency": 3.272.0
-    "@aws-sdk/middleware-content-length": 3.272.0
-    "@aws-sdk/middleware-endpoint": 3.272.0
-    "@aws-sdk/middleware-host-header": 3.272.0
-    "@aws-sdk/middleware-logger": 3.272.0
-    "@aws-sdk/middleware-recursion-detection": 3.272.0
-    "@aws-sdk/middleware-retry": 3.272.0
-    "@aws-sdk/middleware-sdk-sts": 3.272.0
-    "@aws-sdk/middleware-serde": 3.272.0
-    "@aws-sdk/middleware-signing": 3.272.0
-    "@aws-sdk/middleware-stack": 3.272.0
-    "@aws-sdk/middleware-user-agent": 3.272.0
-    "@aws-sdk/node-config-provider": 3.272.0
-    "@aws-sdk/node-http-handler": 3.272.0
-    "@aws-sdk/protocol-http": 3.272.0
-    "@aws-sdk/smithy-client": 3.272.0
-    "@aws-sdk/types": 3.272.0
-    "@aws-sdk/url-parser": 3.272.0
-    "@aws-sdk/util-base64": 3.208.0
-    "@aws-sdk/util-body-length-browser": 3.188.0
-    "@aws-sdk/util-body-length-node": 3.208.0
-    "@aws-sdk/util-defaults-mode-browser": 3.272.0
-    "@aws-sdk/util-defaults-mode-node": 3.272.0
-    "@aws-sdk/util-endpoints": 3.272.0
-    "@aws-sdk/util-retry": 3.272.0
-    "@aws-sdk/util-user-agent-browser": 3.272.0
-    "@aws-sdk/util-user-agent-node": 3.272.0
-    "@aws-sdk/util-utf8": 3.254.0
-    fast-xml-parser: 4.1.2
-    tslib: ^2.3.1
-  checksum: 2e3083803a4d64de3148ef49b6dccb1a54d6766a8c60a2002cff32f005159d69d8323e50b7cb6055cb0bd595b8e8f2bc8ccd839ee9ca17c5db47fc6b63b10269
-  languageName: node
-  linkType: hard
-
-"@aws-sdk/client-sts@npm:3.276.0, @aws-sdk/client-sts@npm:^3.208.0":
-  version: 3.276.0
-  resolution: "@aws-sdk/client-sts@npm:3.276.0"
-  dependencies:
-    "@aws-crypto/sha256-browser": 3.0.0
-    "@aws-crypto/sha256-js": 3.0.0
-    "@aws-sdk/config-resolver": 3.282.0
-    "@aws-sdk/credential-provider-node": 3.282.0
-    "@aws-sdk/fetch-http-handler": 3.282.0
-    "@aws-sdk/hash-node": 3.272.0
-    "@aws-sdk/invalid-dependency": 3.272.0
-    "@aws-sdk/middleware-content-length": 3.282.0
-    "@aws-sdk/middleware-endpoint": 3.282.0
-    "@aws-sdk/middleware-host-header": 3.282.0
-    "@aws-sdk/middleware-logger": 3.272.0
-    "@aws-sdk/middleware-recursion-detection": 3.282.0
-    "@aws-sdk/middleware-retry": 3.282.0
-    "@aws-sdk/middleware-sdk-sts": 3.282.0
-    "@aws-sdk/middleware-serde": 3.272.0
-    "@aws-sdk/middleware-signing": 3.282.0
-    "@aws-sdk/middleware-stack": 3.272.0
-    "@aws-sdk/middleware-user-agent": 3.282.0
-    "@aws-sdk/node-config-provider": 3.272.0
-    "@aws-sdk/node-http-handler": 3.282.0
-    "@aws-sdk/protocol-http": 3.282.0
-    "@aws-sdk/smithy-client": 3.279.0
-    "@aws-sdk/types": 3.272.0
-    "@aws-sdk/url-parser": 3.272.0
-    "@aws-sdk/util-base64": 3.208.0
-    "@aws-sdk/util-body-length-browser": 3.188.0
-    "@aws-sdk/util-body-length-node": 3.208.0
-    "@aws-sdk/util-defaults-mode-browser": 3.279.0
-    "@aws-sdk/util-defaults-mode-node": 3.282.0
-    "@aws-sdk/util-endpoints": 3.272.0
-    "@aws-sdk/util-retry": 3.272.0
-    "@aws-sdk/util-user-agent-browser": 3.282.0
-    "@aws-sdk/util-user-agent-node": 3.282.0
-    "@aws-sdk/util-utf8": 3.254.0
-    fast-xml-parser: 4.1.2
-    tslib: ^2.3.1
-  checksum: 5af24417f7ef2dbebe6b0c0aa545eeb809e92136bce2b1e7dd07de1159f2308c2d673c3b136440e4137ce7524cbdabe50e80d7ca6f8635a3d9dcd2983532a9e7
-  languageName: node
-  linkType: hard
-
 "@aws-sdk/client-sts@npm:3.282.0, @aws-sdk/client-sts@npm:^3.208.0":
   version: 3.282.0
   resolution: "@aws-sdk/client-sts@npm:3.282.0"
@@ -1092,50 +1004,6 @@ __metadata:
   languageName: node
   linkType: hard
 
-"@aws-sdk/client-sts@npm:^3.208.0":
-  version: 3.276.0
-  resolution: "@aws-sdk/client-sts@npm:3.276.0"
-  dependencies:
-    "@aws-crypto/sha256-browser": 3.0.0
-    "@aws-crypto/sha256-js": 3.0.0
-    "@aws-sdk/config-resolver": 3.282.0
-    "@aws-sdk/credential-provider-node": 3.282.0
-    "@aws-sdk/fetch-http-handler": 3.282.0
-    "@aws-sdk/hash-node": 3.272.0
-    "@aws-sdk/invalid-dependency": 3.272.0
-    "@aws-sdk/middleware-content-length": 3.282.0
-    "@aws-sdk/middleware-endpoint": 3.282.0
-    "@aws-sdk/middleware-host-header": 3.282.0
-    "@aws-sdk/middleware-logger": 3.272.0
-    "@aws-sdk/middleware-recursion-detection": 3.282.0
-    "@aws-sdk/middleware-retry": 3.282.0
-    "@aws-sdk/middleware-sdk-sts": 3.282.0
-    "@aws-sdk/middleware-serde": 3.272.0
-    "@aws-sdk/middleware-signing": 3.282.0
-    "@aws-sdk/middleware-stack": 3.272.0
-    "@aws-sdk/middleware-user-agent": 3.282.0
-    "@aws-sdk/node-config-provider": 3.272.0
-    "@aws-sdk/node-http-handler": 3.282.0
-    "@aws-sdk/protocol-http": 3.282.0
-    "@aws-sdk/smithy-client": 3.279.0
-    "@aws-sdk/types": 3.272.0
-    "@aws-sdk/url-parser": 3.272.0
-    "@aws-sdk/util-base64": 3.208.0
-    "@aws-sdk/util-body-length-browser": 3.188.0
-    "@aws-sdk/util-body-length-node": 3.208.0
-    "@aws-sdk/util-defaults-mode-browser": 3.279.0
-    "@aws-sdk/util-defaults-mode-node": 3.282.0
-    "@aws-sdk/util-endpoints": 3.272.0
-    "@aws-sdk/util-retry": 3.272.0
-    "@aws-sdk/util-user-agent-browser": 3.282.0
-    "@aws-sdk/util-user-agent-node": 3.282.0
-    "@aws-sdk/util-utf8": 3.254.0
-    fast-xml-parser: 4.1.2
-    tslib: ^2.3.1
-  checksum: 5af24417f7ef2dbebe6b0c0aa545eeb809e92136bce2b1e7dd07de1159f2308c2d673c3b136440e4137ce7524cbdabe50e80d7ca6f8635a3d9dcd2983532a9e7
-  languageName: node
-  linkType: hard
-
 "@aws-sdk/config-resolver@npm:3.282.0":
   version: 3.282.0
   resolution: "@aws-sdk/config-resolver@npm:3.282.0"
@@ -1160,18 +1028,6 @@ __metadata:
   languageName: node
   linkType: hard
 
-"@aws-sdk/credential-provider-cognito-identity@npm:3.276.0":
-  version: 3.276.0
-  resolution: "@aws-sdk/credential-provider-cognito-identity@npm:3.276.0"
-  dependencies:
-    "@aws-sdk/client-cognito-identity": 3.276.0
-    "@aws-sdk/property-provider": 3.272.0
-    "@aws-sdk/types": 3.272.0
-    tslib: ^2.3.1
-  checksum: 2d255475f08beeccd000745b2f2c46553559fd6fe15c0ea9960956655535fb927df9ec3431cf743b80f9a460d033ede7e1c47e91aff44956559a70c5f43f7bab
-  languageName: node
-  linkType: hard
-
 "@aws-sdk/credential-provider-cognito-identity@npm:3.282.0":
   version: 3.282.0
   resolution: "@aws-sdk/credential-provider-cognito-identity@npm:3.282.0"
@@ -1293,13 +1149,13 @@ __metadata:
   linkType: hard
 
 "@aws-sdk/credential-providers@npm:^3.208.0":
-  version: 3.276.0
-  resolution: "@aws-sdk/credential-providers@npm:3.276.0"
+  version: 3.282.0
+  resolution: "@aws-sdk/credential-providers@npm:3.282.0"
   dependencies:
-    "@aws-sdk/client-cognito-identity": 3.276.0
-    "@aws-sdk/client-sso": 3.272.0
-    "@aws-sdk/client-sts": 3.276.0
-    "@aws-sdk/credential-provider-cognito-identity": 3.276.0
+    "@aws-sdk/client-cognito-identity": 3.282.0
+    "@aws-sdk/client-sso": 3.282.0
+    "@aws-sdk/client-sts": 3.282.0
+    "@aws-sdk/credential-provider-cognito-identity": 3.282.0
     "@aws-sdk/credential-provider-env": 3.272.0
     "@aws-sdk/credential-provider-imds": 3.272.0
     "@aws-sdk/credential-provider-ini": 3.282.0
@@ -1311,7 +1167,7 @@ __metadata:
     "@aws-sdk/shared-ini-file-loader": 3.272.0
     "@aws-sdk/types": 3.272.0
     tslib: ^2.3.1
-  checksum: 825fb0feda57ef98cc11ab3febc2a337161193dfa24bcc31ad2b47ecb4af564b3b5a5a0d9c17fd1a3ec118321d21fc515948980ba50c323e21ed79905c13dfe4
+  checksum: ec707176eba558fc5bfc45b2917d624a83995c75bfc38a121d3a3fe6c0be541c25815d4892fc33fd0f1de5f892232014724b0d5c62c19a2d6d3f839258b25840
   languageName: node
   linkType: hard
 
@@ -1437,8 +1293,8 @@ __metadata:
   linkType: hard
 
 "@aws-sdk/lib-storage@npm:^3.208.0":
-  version: 3.276.0
-  resolution: "@aws-sdk/lib-storage@npm:3.276.0"
+  version: 3.282.0
+  resolution: "@aws-sdk/lib-storage@npm:3.282.0"
   dependencies:
     "@aws-sdk/middleware-endpoint": 3.299.0
     "@aws-sdk/smithy-client": 3.296.0
@@ -1449,7 +1305,7 @@ __metadata:
   peerDependencies:
     "@aws-sdk/abort-controller": ^3.0.0
     "@aws-sdk/client-s3": ^3.0.0
-  checksum: 1e34d3569c8cf2f7c42efdd7966a9faea64bf49f4fe1fcb0ff30ed86670a5ba2361bb14279e7dc1bc110a1ff9e5cec3551bc8a56b3c9c4d19f98ff4842a8de19
+  checksum: 14f1f21a653d239721ca488b6d7951511576a2e2652d240f3561ac0255cd4af321bc41531c15c3c6fae4095da062f5e841c6c9b58afd80be9bf105b63a256f72
   languageName: node
   linkType: hard
 
@@ -15948,7 +15804,7 @@ __metadata:
   languageName: node
   linkType: hard
 
-"@types/express-serve-static-core@npm:*, @types/express-serve-static-core@npm:^4.17.18, @types/express-serve-static-core@npm:^4.17.33, @types/express-serve-static-core@npm:^4.17.5":
+"@types/express-serve-static-core@npm:*, @types/express-serve-static-core@npm:^4.17.18, @types/express-serve-static-core@npm:^4.17.31, @types/express-serve-static-core@npm:^4.17.33, @types/express-serve-static-core@npm:^4.17.5":
   version: 4.17.33
   resolution: "@types/express-serve-static-core@npm:4.17.33"
   dependencies:
@@ -16001,14 +15857,14 @@ __metadata:
   linkType: hard
 
 "@types/express@npm:*, @types/express@npm:^4.17.13, @types/express@npm:^4.17.6":
-  version: 4.17.17
-  resolution: "@types/express@npm:4.17.17"
+  version: 4.17.16
+  resolution: "@types/express@npm:4.17.16"
   dependencies:
     "@types/body-parser": "*"
-    "@types/express-serve-static-core": ^4.17.33
+    "@types/express-serve-static-core": ^4.17.31
     "@types/qs": "*"
     "@types/serve-static": "*"
-  checksum: 0196dacc275ac3ce89d7364885cb08e7fb61f53ca101f65886dbf1daf9b7eb05c0943e2e4bbd01b0cc5e50f37e0eea7e4cbe97d0304094411ac73e1b7998f4da
+  checksum: 43f3ed2cea6e5e83c7c1098c5152f644e975fd764443717ff9c812a1518416a9e7e9f824ffe852c118888cbfb994ed023cad08331f49b19ced469bb185cdd5cd
   languageName: node
   linkType: hard
 
@@ -28764,14 +28620,13 @@ __metadata:
   linkType: hard
 
 "json-schema-to-ts@npm:^2.6.2":
-  version: 2.6.2
-  resolution: "json-schema-to-ts@npm:2.6.2"
+  version: 2.7.2
+  resolution: "json-schema-to-ts@npm:2.7.2"
   dependencies:
     "@babel/runtime": ^7.18.3
     "@types/json-schema": ^7.0.9
-    ts-algebra: ^1.1.1
-    ts-toolbelt: ^9.6.0
-  checksum: e408f8d3d32dda1a001f194cf5514fea7ef0a4dc4ed4f5448b9ea02df3a071119a0517aaffb639de725f4a12102406dfdf7743455e0e30317e231bb551362039
+    ts-algebra: ^1.2.0
+  checksum: cc359d3b2aed035b550582e85989a6fdd4d54bbfd5a2933c9a1e242709a04a7babdba53f5c22280e11b4bd9730b08a933d060fc69810814310908cce76f9e152
   languageName: node
   linkType: hard
 
@@ -38946,12 +38801,10 @@ __metadata:
   languageName: node
   linkType: hard
 
-"ts-algebra@npm:^1.1.1":
-  version: 1.1.1
-  resolution: "ts-algebra@npm:1.1.1"
-  dependencies:
-    ts-toolbelt: ^9.6.0
-  checksum: 29fe27215863520377a94a14ccf1e78e921be6a5c514a0a8250dab09e325b006a9571ef1f366875d58e495b59ba880620718a1dd38b6af598cc6ea6de82d4f66
+"ts-algebra@npm:^1.2.0":
+  version: 1.2.0
+  resolution: "ts-algebra@npm:1.2.0"
+  checksum: 471d3a049dbceadf2355f980e4d0a4cba413b50e66f0c8fb5eece876c238f7d2a270e1c85aa9ebd04349ae70335715f8e6d87338fd8cf755d12e285e884b3d91
   languageName: node
   linkType: hard
 

From 759ba30501c6e4cfc41032fd67ffa2befce352f6 Mon Sep 17 00:00:00 2001
From: Aramis Sennyey <sennyeya@amazon.com>
Date: Tue, 14 Mar 2023 15:45:16 -0400
Subject: [PATCH 45/61] Update schema to get rid of nullable which isn't valid
 3.1.

Signed-off-by: Aramis Sennyey <sennyeya@amazon.com>
---
 plugins/catalog-backend/openapi.yaml      | 7 ++++---
 plugins/catalog-backend/schema/openapi.ts | 6 ++++--
 2 files changed, 8 insertions(+), 5 deletions(-)

diff --git a/plugins/catalog-backend/openapi.yaml b/plugins/catalog-backend/openapi.yaml
index ecab6c7272..32f0e04e58 100644
--- a/plugins/catalog-backend/openapi.yaml
+++ b/plugins/catalog-backend/openapi.yaml
@@ -257,7 +257,7 @@ components:
           items:
             allOf:
               - $ref: '#/components/schemas/Entity'
-            nullable: true
+              - type: 'null'
           description: |-
             The list of entities, in the same order as the refs in the request. Entries
             that are null signify that no entity existed with that ref.
@@ -455,8 +455,9 @@ components:
             field empty; which would currently make it owned by X" where X is taken from the
             codeowners file.
         value:
-          type: string
-          nullable: true
+          type:
+            - string
+            - 'null'
         state:
           type: string
           enum:
diff --git a/plugins/catalog-backend/schema/openapi.ts b/plugins/catalog-backend/schema/openapi.ts
index e14410cd30..b7e2220b55 100644
--- a/plugins/catalog-backend/schema/openapi.ts
+++ b/plugins/catalog-backend/schema/openapi.ts
@@ -306,12 +306,14 @@ export default {
           items: {
             type: 'array',
             items: {
-              allOf: [
+              anyOf: [
                 {
                   $ref: '#/components/schemas/Entity',
                 },
+                {
+                  type: 'null',
+                },
               ],
-              nullable: true,
             },
             description:
               'The list of entities, in the same order as the refs in the request. Entries\nthat are null signify that no entity existed with that ref.',

From 3be54cd5e55c296ed8d60d9c386eb6e95b2909f6 Mon Sep 17 00:00:00 2001
From: Aramis Sennyey <sennyeya@amazon.com>
Date: Tue, 14 Mar 2023 16:21:31 -0400
Subject: [PATCH 46/61] Fix schema.

Signed-off-by: Aramis Sennyey <sennyeya@amazon.com>
---
 plugins/catalog-backend/openapi.yaml      | 2 +-
 plugins/catalog-backend/schema/openapi.ts | 3 +--
 2 files changed, 2 insertions(+), 3 deletions(-)

diff --git a/plugins/catalog-backend/openapi.yaml b/plugins/catalog-backend/openapi.yaml
index 32f0e04e58..72e04d0277 100644
--- a/plugins/catalog-backend/openapi.yaml
+++ b/plugins/catalog-backend/openapi.yaml
@@ -255,7 +255,7 @@ components:
         items:
           type: array
           items:
-            allOf:
+            anyOf:
               - $ref: '#/components/schemas/Entity'
               - type: 'null'
           description: |-
diff --git a/plugins/catalog-backend/schema/openapi.ts b/plugins/catalog-backend/schema/openapi.ts
index b7e2220b55..504b67c6de 100644
--- a/plugins/catalog-backend/schema/openapi.ts
+++ b/plugins/catalog-backend/schema/openapi.ts
@@ -524,8 +524,7 @@ export default {
               'A text to show to the user to inform about the choices made. Like, it could say\n"Found a CODEOWNERS file that covers this target, so we suggest leaving this\nfield empty; which would currently make it owned by X" where X is taken from the\ncodeowners file.',
           },
           value: {
-            type: 'string',
-            nullable: true,
+            type: ['string', 'null'],
           },
           state: {
             type: 'string',

From 577f36c3a6e4acfd255cc0fac87efa2062f9ae7e Mon Sep 17 00:00:00 2001
From: Aramis Sennyey <sennyeya@amazon.com>
Date: Wed, 15 Mar 2023 12:16:41 -0400
Subject: [PATCH 47/61] Update spec with better parameters and fix conflict in
 yarn.lock.

Signed-off-by: Aramis Sennyey <sennyeya@amazon.com>
---
 plugins/catalog-backend/openapi.yaml      | 73 ++++++++++-------------
 plugins/catalog-backend/schema/openapi.ts | 22 ++-----
 yarn.lock                                 |  2 +-
 3 files changed, 39 insertions(+), 58 deletions(-)

diff --git a/plugins/catalog-backend/openapi.yaml b/plugins/catalog-backend/openapi.yaml
index 72e04d0277..a52cc9235f 100644
--- a/plugins/catalog-backend/openapi.yaml
+++ b/plugins/catalog-backend/openapi.yaml
@@ -47,6 +47,15 @@ components:
       required: false
       schema:
         type: string
+        minLength: 1
+    after:
+      name: after
+      in: query
+      description: Pointer to the previous page of results.
+      required: false
+      schema:
+        type: string
+        minLength: 1
     fields:
       name: fields
       in: query
@@ -54,6 +63,21 @@ components:
       required: false
       schema:
         type: string
+    filter:
+      name: filter
+      in: query
+      description: Filter for just the entities defined by this filter.
+      required: false
+      schema:
+        type: string
+    offset:
+      name: offset
+      in: query
+      description: Number of records to skip in the query page.
+      required: false
+      schema:
+        type: integer
+        minimum: 1
     limit:
       name: limit
       in: query
@@ -74,7 +98,6 @@ components:
           items:
             type: string
           description: A two-item tuple of [field, order].
-
       explode: true
       style: form
   requestBodies: {}
@@ -620,31 +643,11 @@ paths:
         - {}
         - JWT: []
       parameters:
-        - in: query
-          name: filter
-          required: false
-          schema:
-            type: string
-        - in: query
-          name: fields
-          required: false
-          schema:
-            type: string
-        - in: query
-          name: offset
-          required: false
-          schema:
-            type: string
-        - in: query
-          name: limit
-          required: false
-          schema:
-            type: string
-        - in: query
-          name: after
-          required: false
-          schema:
-            type: string
+        - $ref: '#/components/parameters/fields'
+        - $ref: '#/components/parameters/limit'
+        - $ref: '#/components/parameters/filter'
+        - $ref: '#/components/parameters/offset'
+        - $ref: '#/components/parameters/after'
   /entities/by-uid/{uid}:
     get:
       operationId: GetEntityByUid
@@ -669,11 +672,7 @@ paths:
         - {}
         - JWT: []
       parameters:
-        - in: path
-          name: uid
-          required: true
-          schema:
-            type: string
+        - $ref: '#/components/parameters/uid'
   /entities/by-name/{kind}/{namespace}/{name}:
     get:
       operationId: GetEntityByName
@@ -722,11 +721,7 @@ paths:
         - {}
         - JWT: []
       parameters:
-        - in: query
-          name: fields
-          required: false
-          schema:
-            type: string
+        - $ref: '#/components/parameters/fields'
       requestBody:
         required: true
         content:
@@ -797,11 +792,7 @@ paths:
           required: true
           schema:
             type: string
-        - in: query
-          name: filter
-          required: false
-          schema:
-            type: string
+        - $ref: '#/components/parameters/filter'
   /locations:
     post:
       operationId: CreateLocation
diff --git a/plugins/catalog-backend/schema/openapi.ts b/plugins/catalog-backend/schema/openapi.ts
index 504b67c6de..b0078644f2 100644
--- a/plugins/catalog-backend/schema/openapi.ts
+++ b/plugins/catalog-backend/schema/openapi.ts
@@ -736,6 +736,12 @@ export default {
           },
         ],
         parameters: [
+          {
+            $ref: '#/components/parameters/fields',
+          },
+          {
+            $ref: '#/components/parameters/limit',
+          },
           {
             in: 'query',
             name: 'filter',
@@ -744,14 +750,6 @@ export default {
               type: 'string',
             },
           },
-          {
-            in: 'query',
-            name: 'fields',
-            required: false,
-            schema: {
-              type: 'string',
-            },
-          },
           {
             in: 'query',
             name: 'offset',
@@ -760,14 +758,6 @@ export default {
               type: 'string',
             },
           },
-          {
-            in: 'query',
-            name: 'limit',
-            required: false,
-            schema: {
-              type: 'string',
-            },
-          },
           {
             in: 'query',
             name: 'after',
diff --git a/yarn.lock b/yarn.lock
index d40dfd3ea3..61e2f01c05 100644
--- a/yarn.lock
+++ b/yarn.lock
@@ -40807,7 +40807,7 @@ __metadata:
   languageName: node
   linkType: hard
 
-"yaml@npm:^2.0.0, yaml@npm:^2.1.1, yaml@npm:^2.1.3, yaml@npm:^2.2.1":
+"yaml@npm:^2.0.0, yaml@npm:^2.1.1, yaml@npm:^2.2.1":
   version: 2.2.1
   resolution: "yaml@npm:2.2.1"
   checksum: 84f68cbe462d5da4e7ded4a8bded949ffa912bc264472e5a684c3d45b22d8f73a3019963a32164023bdf3d83cfb6f5b58ff7b2b10ef5b717c630f40bd6369a23

From 4efe0a0877dd996ea8ed730ad5443ff1e6578df2 Mon Sep 17 00:00:00 2001
From: Aramis Sennyey <sennyeya@amazon.com>
Date: Wed, 15 Mar 2023 12:17:23 -0400
Subject: [PATCH 48/61] Update schema.

Signed-off-by: Aramis Sennyey <sennyeya@amazon.com>
---
 plugins/catalog-backend/schema/openapi.ts | 72 +++++++++++------------
 1 file changed, 36 insertions(+), 36 deletions(-)

diff --git a/plugins/catalog-backend/schema/openapi.ts b/plugins/catalog-backend/schema/openapi.ts
index b0078644f2..be58a2ea74 100644
--- a/plugins/catalog-backend/schema/openapi.ts
+++ b/plugins/catalog-backend/schema/openapi.ts
@@ -74,6 +74,17 @@ export default {
         required: false,
         schema: {
           type: 'string',
+          minLength: 1,
+        },
+      },
+      after: {
+        name: 'after',
+        in: 'query',
+        description: 'Pointer to the previous page of results.',
+        required: false,
+        schema: {
+          type: 'string',
+          minLength: 1,
         },
       },
       fields: {
@@ -85,6 +96,25 @@ export default {
           type: 'string',
         },
       },
+      filter: {
+        name: 'filter',
+        in: 'query',
+        description: 'Filter for just the entities defined by this filter.',
+        required: false,
+        schema: {
+          type: 'string',
+        },
+      },
+      offset: {
+        name: 'offset',
+        in: 'query',
+        description: 'Number of records to skip in the query page.',
+        required: false,
+        schema: {
+          type: 'integer',
+          minimum: 1,
+        },
+      },
       limit: {
         name: 'limit',
         in: 'query',
@@ -743,28 +773,13 @@ export default {
             $ref: '#/components/parameters/limit',
           },
           {
-            in: 'query',
-            name: 'filter',
-            required: false,
-            schema: {
-              type: 'string',
-            },
+            $ref: '#/components/parameters/filter',
           },
           {
-            in: 'query',
-            name: 'offset',
-            required: false,
-            schema: {
-              type: 'string',
-            },
+            $ref: '#/components/parameters/offset',
           },
           {
-            in: 'query',
-            name: 'after',
-            required: false,
-            schema: {
-              type: 'string',
-            },
+            $ref: '#/components/parameters/after',
           },
         ],
       },
@@ -811,12 +826,7 @@ export default {
         ],
         parameters: [
           {
-            in: 'path',
-            name: 'uid',
-            required: true,
-            schema: {
-              type: 'string',
-            },
+            $ref: '#/components/parameters/uid',
           },
         ],
       },
@@ -912,12 +922,7 @@ export default {
         ],
         parameters: [
           {
-            in: 'query',
-            name: 'fields',
-            required: false,
-            schema: {
-              type: 'string',
-            },
+            $ref: '#/components/parameters/fields',
           },
         ],
         requestBody: {
@@ -1039,12 +1044,7 @@ export default {
             },
           },
           {
-            in: 'query',
-            name: 'filter',
-            required: false,
-            schema: {
-              type: 'string',
-            },
+            $ref: '#/components/parameters/filter',
           },
         ],
       },

From abd4ff4cee71798534c3fac47a2fc6e7dada4252 Mon Sep 17 00:00:00 2001
From: Aramis Sennyey <sennyeya@amazon.com>
Date: Thu, 16 Mar 2023 12:13:17 -0400
Subject: [PATCH 49/61] Update api report and shift openapi-utils to a
 devDependency.

Signed-off-by: Aramis Sennyey <sennyeya@amazon.com>
---
 plugins/catalog-backend/openapi.yaml          |   2 +-
 plugins/catalog-backend/package.json          |   2 +-
 .../src/service/createRouter.ts               |   2 +-
 plugins/openapi-utils/README.md               |  46 +-
 plugins/openapi-utils/api-report.md           | 591 +-----------------
 plugins/openapi-utils/package.json            |   2 +-
 plugins/openapi-utils/src/example.ts          |  50 --
 plugins/openapi-utils/src/router.ts           |  20 +-
 plugins/openapi-utils/src/schema/petstore.ts  | 183 ------
 plugins/openapi-utils/src/types/common.ts     |  86 +--
 plugins/openapi-utils/src/types/express.ts    |  15 +-
 plugins/openapi-utils/src/types/immutable.ts  |  57 +-
 plugins/openapi-utils/src/types/index.ts      |  36 +-
 plugins/openapi-utils/src/types/params.ts     |  42 +-
 plugins/openapi-utils/src/types/requests.ts   |  11 +-
 plugins/openapi-utils/src/types/responses.ts  |  21 +-
 yarn.lock                                     |  46 +-
 17 files changed, 94 insertions(+), 1118 deletions(-)
 delete mode 100644 plugins/openapi-utils/src/example.ts
 delete mode 100644 plugins/openapi-utils/src/schema/petstore.ts

diff --git a/plugins/catalog-backend/openapi.yaml b/plugins/catalog-backend/openapi.yaml
index a52cc9235f..d2dd74fb33 100644
--- a/plugins/catalog-backend/openapi.yaml
+++ b/plugins/catalog-backend/openapi.yaml
@@ -77,7 +77,7 @@ components:
       required: false
       schema:
         type: integer
-        minimum: 1
+        minimum: 0
     limit:
       name: limit
       in: query
diff --git a/plugins/catalog-backend/package.json b/plugins/catalog-backend/package.json
index 2d77c724c5..bdbf242590 100644
--- a/plugins/catalog-backend/package.json
+++ b/plugins/catalog-backend/package.json
@@ -46,7 +46,6 @@
   },
   "dependencies": {
     "@backstage/backend-common": "workspace:^",
-    "@backstage/backend-openapi-utils": "workspace:^",
     "@backstage/backend-plugin-api": "workspace:^",
     "@backstage/catalog-client": "workspace:^",
     "@backstage/catalog-model": "workspace:^",
@@ -85,6 +84,7 @@
     "zod": "^3.21.4"
   },
   "devDependencies": {
+    "@backstage/backend-openapi-utils": "workspace:^",
     "@backstage/backend-test-utils": "workspace:^",
     "@backstage/cli": "workspace:^",
     "@backstage/plugin-permission-common": "workspace:^",
diff --git a/plugins/catalog-backend/src/service/createRouter.ts b/plugins/catalog-backend/src/service/createRouter.ts
index 77fe4a24e8..3aff802660 100644
--- a/plugins/catalog-backend/src/service/createRouter.ts
+++ b/plugins/catalog-backend/src/service/createRouter.ts
@@ -50,7 +50,7 @@ import {
   locationInput,
   validateRequestBody,
 } from './util';
-import { ApiRouter } from '@backstage/backend-openapi-utils';
+import type { ApiRouter } from '@backstage/backend-openapi-utils';
 import spec from '../../schema/openapi';
 
 /**
diff --git a/plugins/openapi-utils/README.md b/plugins/openapi-utils/README.md
index 882b99b698..04344baa9d 100644
--- a/plugins/openapi-utils/README.md
+++ b/plugins/openapi-utils/README.md
@@ -1,55 +1,45 @@
-# @backstage/plugin-openapi-router
+# @backstage/openapi-utils
 
-## Purpose
+## Summary
 
-This package is meant to provide a typed Express router for an OpenAPI spec. Specs must be converted to JSON and then copied to a Typescript file.
+This package is meant to provide a typed Express router for an OpenAPI spec. Based on the [oatx](https://github.com/varanauskas/oatx) library and adapted to override Express values.
 
 ## Getting Started
 
 ### Configuration
 
-In your plugin's `schema/openapi.ts`,
+1. Run `yarn --cwd <package-dir> backstage-cli package schema:openapi:generate` to translate your `openapi.yaml` to a new Typescript file in `schema/openapi.ts`. In the case of projects that require linting + a license header, you will need to do this manually.
+
+2. In your plugin's `src/service/createRouter.ts`,
 
 ```ts
-export default {
-  // If your spec is in YAML, convert it to JSON, then paste it here.
-  // If your spec is in JSON, just paste it here.
-} as const;
-```
-
-In your plugin's `service/createRouter.ts`,
-
-```ts
-import {ApiRouter} from `@backstage/plugin-openapi-router`;
-import spec from './schema/openapi'
+import {ApiRouter} from `@backstage/backend-openapi-utils`;
+import spec from '../../schema/openapi'
 ...
 
 export function createRouter(){
-    const router = Router() as ApiRouter<typeof spec>
+    const router = Router() as ApiRouter<typeof spec>;
+    ...
 }
 ```
 
 ### Limitations
 
-1. OpenAPI definitions must be converted to Typescript files
-   From [#32063](https://github.com/microsoft/TypeScript/issues/32063), we cannot import JSON `as const`. If we could, this would allow us to force all specs to be JSON and then just import from a spec.
-2. `as const` makes all fields `readonly`
-   To ensure a good DX of using a simple imported JSON spec, we want to remove any type issues between `readonly` arrays and mutable arrays. Typescript does not allow them to be compared, so converting all imports from the `openapi3-ts` library to `readonly` is important.
+1. `as const` makes all fields `readonly`
+   To ensure a good DX of using a simple imported JSON spec, we want to remove any type issues between `readonly` arrays and mutable arrays. Typescript does not allow them to be compared, so converting all imports from the `openapi3-ts` library to `readonly` is important. This is achieved through the `ImmutableObject` type in `types/immutable.ts`.
 
-```tsx
+```ts
 ...
+// We want an interface like this,
 Router() as ApiRouter<typeof spec>
+
+// Not an interface like this,
+Router() as ApiRouter<DeepWriteable<typeof spec>>
 ...
 ```
 
-we need to type all internals of this package as `Immutable<T>`.
-
 ## Future Work
 
 ### Runtime validation
 
-Using a package like [`express-openapi-validator`](https://www.npmjs.com/package/express-openapi-validator), would allow us to remove [validation of request bodies with `AJV`](https://github.com/backstage/backstage/blob/master/plugins/catalog-backend/src/service/util.ts#L58).
-
-### PR-time verification.
-
-1. Verify that spec file matches the router input/output.
+Using a package like [`express-openapi-validator`](https://www.npmjs.com/package/express-openapi-validator), would allow us to remove [validation of request bodies with `AJV`](https://github.com/backstage/backstage/blob/master/plugins/catalog-backend/src/service/util.ts#L58). However, `AJV` currently doesn't have support for OpenAPI 3.1 and `express-openapi-validator` enforces full URL matching for paths, meaning it cannot be mounted at the router level.
diff --git a/plugins/openapi-utils/api-report.md b/plugins/openapi-utils/api-report.md
index a51fd8e4f7..7e5024b15b 100644
--- a/plugins/openapi-utils/api-report.md
+++ b/plugins/openapi-utils/api-report.md
@@ -3,599 +3,28 @@
 > Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.com/).
 
 ```ts
-import type { ContentObject } from 'openapi3-ts';
-import core from 'express-serve-static-core';
-import { FromSchema } from 'json-schema-to-ts';
-import { JSONSchema7 } from 'json-schema-to-ts';
-import type { OpenAPIObject } from 'openapi3-ts';
-import type { ParameterObject } from 'openapi3-ts';
-import type { ReferenceObject } from 'openapi3-ts';
-import type { RequestBodyObject } from 'openapi3-ts';
-import type { ResponseObject } from 'openapi3-ts';
 import { Router } from 'express';
-import type { SchemaObject } from 'openapi3-ts';
 
 // @public
-export interface ApiRouter<Doc extends RequiredDoc> extends Router {
+export interface ApiRouter<Doc extends core.Spec> extends Router {
   // (undocumented)
-  all: DocRequestMatcher<Doc, this, 'all'>;
+  all: core.RequestMatcher<Doc, this, 'all'>;
   // (undocumented)
-  delete: DocRequestMatcher<Doc, this, 'delete'>;
+  delete: core.RequestMatcher<Doc, this, 'delete'>;
   // (undocumented)
-  get: DocRequestMatcher<Doc, this, 'get'>;
+  get: core.RequestMatcher<Doc, this, 'get'>;
   // (undocumented)
-  head: DocRequestMatcher<Doc, this, 'head'>;
+  head: core.RequestMatcher<Doc, this, 'head'>;
   // (undocumented)
-  options: DocRequestMatcher<Doc, this, 'options'>;
+  options: core.RequestMatcher<Doc, this, 'options'>;
   // (undocumented)
-  patch: DocRequestMatcher<Doc, this, 'patch'>;
+  patch: core.RequestMatcher<Doc, this, 'patch'>;
   // (undocumented)
-  post: DocRequestMatcher<Doc, this, 'post'>;
+  post: core.RequestMatcher<Doc, this, 'post'>;
   // (undocumented)
-  put: DocRequestMatcher<Doc, this, 'put'>;
+  put: core.RequestMatcher<Doc, this, 'put'>;
 }
 
 // @public (undocumented)
-export type ComponentRef<
-  Doc extends RequiredDoc,
-  Type extends ComponentTypes<Doc>,
-  Ref extends ImmutableReferenceObject,
-> = Ref extends {
-  $ref: `#/components/${Type}/${infer Name}`;
-}
-  ? Name extends keyof Doc['components'][Type]
-    ? Doc['components'][Type][Name] extends ImmutableReferenceObject
-      ? ComponentRef<Doc, Type, Doc['components'][Type][Name]>
-      : Doc['components'][Type][Name]
-    : never
-  : never;
-
-// @public (undocumented)
-export type ComponentTypes<Doc extends RequiredDoc> = Extract<
-  keyof Doc['components'],
-  string
->;
-
-// @public (undocumented)
-export type ConvertAll<T, R extends ReadonlyArray<unknown> = []> = T extends [
-  infer First extends JSONSchema7,
-  ...infer Rest,
-]
-  ? ConvertAll<Rest, [...R, FromSchema<First>]>
-  : R;
-
-// @public (undocumented)
-export interface CookieObject extends ParameterObject {
-  // (undocumented)
-  in: 'cookie';
-  // (undocumented)
-  style?: 'form';
-}
-
-// @public (undocumented)
-export type CookieSchema<
-  Doc extends RequiredDoc,
-  Path extends PathTemplate<Extract<keyof Doc['paths'], string>>,
-  Method extends DocPathMethod<Doc, Path>,
-> = ParametersSchema<Doc, DocPath<Doc, Path>, Method, ImmutableCookieObject>;
-
-// @public (undocumented)
-export type DiscriminateUnion<T, K extends keyof T, V extends T[K]> = Extract<
-  T,
-  Record<K, V>
->;
-
-// @public (undocumented)
-export type DocOperation<
-  Doc extends RequiredDoc,
-  Path extends keyof Doc['paths'],
-  Method extends keyof Doc['paths'][Path],
-> = Doc['paths'][Path][Method];
-
-// @public (undocumented)
-export type DocParameter<
-  Doc extends RequiredDoc,
-  Path extends Extract<keyof Doc['paths'], string>,
-  Method extends keyof Doc['paths'][Path],
-  Parameter extends keyof Doc['paths'][Path][Method]['parameters'],
-> = DocOperation<
-  Doc,
-  Path,
-  Method
->['parameters'][Parameter] extends ImmutableReferenceObject
-  ? 'parameters' extends ComponentTypes<Doc>
-    ? ComponentRef<
-        Doc,
-        'parameters',
-        DocOperation<Doc, Path, Method>['parameters'][Parameter]
-      >
-    : never
-  : DocOperation<Doc, Path, Method>['parameters'][Parameter];
-
-// @public (undocumented)
-export type DocParameters<
-  Doc extends RequiredDoc,
-  Path extends Extract<keyof Doc['paths'], string>,
-  Method extends keyof Doc['paths'][Path],
-> = DocOperation<Doc, Path, Method>['parameters'] extends ReadonlyArray<any>
-  ? {
-      [Index in keyof DocOperation<
-        Doc,
-        Path,
-        Method
-      >['parameters']]: DocParameter<Doc, Path, Method, Index>;
-    }
-  : never;
-
-// @public
-export type DocPath<
-  Doc extends PathDoc,
-  Path extends PathTemplate<Extract<keyof Doc['paths'], string>>,
-> = ValueOf<{
-  [Template in Extract<
-    keyof Doc['paths'],
-    string
-  >]: Path extends PathTemplate<Template> ? Template : never;
-}>;
-
-// @public (undocumented)
-export type DocPathMethod<
-  Doc extends Pick<RequiredDoc, 'paths'>,
-  Path extends DocPathTemplate<Doc>,
-> = keyof Doc['paths'][DocPath<Doc, Path>];
-
-// @public (undocumented)
-export type DocPathTemplate<Doc extends PathDoc> = PathTemplate<
-  Extract<keyof Doc['paths'], string>
->;
-
-// @public
-export type DocRequestHandler<
-  Doc extends RequiredDoc,
-  Path extends DocPathTemplate<Doc>,
-  Method extends keyof Doc['paths'][Path],
-> = core.RequestHandler<
-  PathSchema<Doc, Path, Method>,
-  ResponseBodyToJsonSchema<Doc, Path, Method>,
-  RequestBodyToJsonSchema<Doc, Path, Method>,
-  QuerySchema<Doc, Path, Method>,
-  Record<string, string>
->;
-
-// @public
-export type DocRequestHandlerParams<
-  Doc extends RequiredDoc,
-  Path extends DocPathTemplate<Doc>,
-  Method extends keyof Doc['paths'][Path],
-> = core.RequestHandlerParams<
-  PathSchema<Doc, Path, Method>,
-  ResponseBodyToJsonSchema<Doc, Path, Method>,
-  RequestBodyToJsonSchema<Doc, Path, Method>,
-  QuerySchema<Doc, Path, Method>,
-  Record<string, string>
->;
-
-// @public
-export interface DocRequestMatcher<
-  Doc extends RequiredDoc,
-  T,
-  Method extends
-    | 'all'
-    | 'get'
-    | 'post'
-    | 'put'
-    | 'delete'
-    | 'patch'
-    | 'options'
-    | 'head',
-> {
-  // (undocumented)
-  <Path extends MethodAwareDocPath<Doc, DocPathTemplate<Doc>, Method>>(
-    path: Path,
-    ...handlers: Array<DocRequestHandler<Doc, Path, Method>>
-  ): T;
-  // (undocumented)
-  <Path extends MethodAwareDocPath<Doc, DocPathTemplate<Doc>, Method>>(
-    path: Path,
-    ...handlers: Array<DocRequestHandlerParams<Doc, Path, Method>>
-  ): T;
-}
-
-// @public (undocumented)
-export type Filter<T, U> = T extends U ? T : never;
-
-// @public (undocumented)
-export type FullMap<
-  T extends {
-    [key: string]: any;
-  },
-> = RequiredMap<T> & OptionalMap<T>;
-
-// @public (undocumented)
-export interface HeaderObject extends ParameterObject {
-  // (undocumented)
-  in: 'header';
-  // (undocumented)
-  style: 'simple';
-}
-
-// @public (undocumented)
-export type HeaderSchema<
-  Doc extends RequiredDoc,
-  Path extends PathTemplate<Extract<keyof Doc['paths'], string>>,
-  Method extends DocPathMethod<Doc, Path>,
-> = ParametersSchema<Doc, DocPath<Doc, Path>, Method, ImmutableHeaderObject>;
-
-// @public
-export type Immutable<T> = T extends
-  | Function
-  | boolean
-  | number
-  | string
-  | null
-  | undefined
-  ? T
-  : T extends Map<infer K, infer V>
-  ? ReadonlyMap<Immutable<K>, Immutable<V>>
-  : T extends Set<infer S>
-  ? ReadonlySet<Immutable<S>>
-  : {
-      readonly [P in keyof T]: Immutable<T[P]>;
-    };
-
-// @public (undocumented)
-export type ImmutableContentObject = ImmutableObject<ContentObject>;
-
-// @public (undocumented)
-export type ImmutableCookieObject = ImmutableObject<CookieObject>;
-
-// @public (undocumented)
-export type ImmutableHeaderObject = ImmutableObject<HeaderObject>;
-
-// @public (undocumented)
-export type ImmutableObject<T> = {
-  readonly [K in keyof T]: Immutable<T[K]>;
-};
-
-// @public (undocumented)
-export type ImmutableOpenAPIObject = ImmutableObject<OpenAPIObject>;
-
-// @public (undocumented)
-export type ImmutableParameterObject = ImmutableObject<ParameterObject>;
-
-// @public (undocumented)
-export type ImmutablePathObject = ImmutableObject<PathObject>;
-
-// @public (undocumented)
-export type ImmutableQueryObject = ImmutableObject<QueryObject>;
-
-// @public (undocumented)
-export type ImmutableReferenceObject = ImmutableObject<ReferenceObject>;
-
-// @public (undocumented)
-export type ImmutableRequestBodyObject = ImmutableObject<RequestBodyObject>;
-
-// @public (undocumented)
-export type ImmutableResponseObject = ImmutableObject<ResponseObject>;
-
-// @public (undocumented)
-export type ImmutableSchemaObject = ImmutableObject<SchemaObject>;
-
-// @public (undocumented)
-export type LastOf<T> = UnionToIntersection<
-  T extends any ? () => T : never
-> extends () => infer R
-  ? R
-  : never;
-
-// @public (undocumented)
-export type MapDiscriminatedUnion<
-  T extends Record<K, string>,
-  K extends keyof T,
-> = {
-  [V in T[K]]: DiscriminateUnion<T, K, V>;
-};
-
-// @public (undocumented)
-export type MapToSchema<
-  Doc extends RequiredDoc,
-  T extends Record<string, ImmutableParameterObject>,
-> = {
-  [V in keyof T]: NonNullable<T[V]> extends ImmutableParameterObject
-    ? ParameterSchema<Doc, NonNullable<T[V]>['schema']>
-    : never;
-};
-
-// @public (undocumented)
-export type MethodAwareDocPath<
-  Doc extends PathDoc,
-  Path extends PathTemplate<Extract<keyof Doc['paths'], string>>,
-  Method extends keyof Doc['paths'][Path],
-> = ValueOf<{
-  [Template in Extract<
-    keyof Doc['paths'],
-    string
-  >]: Path extends PathTemplate<Template>
-    ? Method extends DocPathMethod<Doc, Path>
-      ? PathTemplate<Template>
-      : never
-    : never;
-}>;
-
-// @public (undocumented)
-export type ObjectWithContentSchema<
-  Doc extends RequiredDoc,
-  Object extends {
-    content?: ImmutableContentObject;
-  },
-> = Object['content'] extends ImmutableContentObject
-  ? SchemaRef<Doc, Object['content']['application/json']['schema']>
-  : never;
-
-// @public (undocumented)
-export type OptionalMap<
-  T extends {
-    [key: string]: any;
-  },
-> = {
-  [P in Exclude<PickOptionalKeys<T>, undefined>]?: NonNullable<T[P]>;
-};
-
-// @public (undocumented)
-export type ParameterSchema<
-  Doc extends RequiredDoc,
-  Schema extends ImmutableParameterObject['schema'],
-> = ResolveDocParameterSchema<Doc, Schema> extends infer R
-  ? R extends ImmutableSchemaObject
-    ? R extends JSONSchema7
-      ? FromSchema<R>
-      : never
-    : never
-  : never;
-
-// @public (undocumented)
-export type ParametersSchema<
-  Doc extends RequiredDoc,
-  Path extends Extract<keyof Doc['paths'], string>,
-  Method extends keyof Doc['paths'][Path],
-  FilterType extends ImmutableParameterObject,
-> = number extends keyof DocParameters<Doc, Path, Method>
-  ? MapToSchema<
-      Doc,
-      FullMap<
-        MapDiscriminatedUnion<
-          Filter<DocParameters<Doc, Path, Method>[number], FilterType>,
-          'name'
-        >
-      >
-    >
-  : never;
-
-// @public
-export interface ParsedQs {
-  // (undocumented)
-  [key: string]: undefined | string | string[] | ParsedQs | ParsedQs[];
-}
-
-// @public (undocumented)
-export type PathDoc = Pick<ImmutableOpenAPIObject, 'paths'>;
-
-// @public (undocumented)
-export interface PathObject extends ParameterObject {
-  // (undocumented)
-  in: 'path';
-  // (undocumented)
-  style?: 'simple' | 'label' | 'matrix';
-}
-
-// @public (undocumented)
-export type PathSchema<
-  Doc extends RequiredDoc,
-  Path extends PathTemplate<Extract<keyof Doc['paths'], string>>,
-  Method extends DocPathMethod<Doc, Path>,
-> = ParametersSchema<Doc, DocPath<Doc, Path>, Method, ImmutablePathObject>;
-
-// @public
-export type PathTemplate<Path extends string> =
-  Path extends `${infer Prefix}{${infer PathName}}${infer Suffix}`
-    ? `${Prefix}:${PathName}${PathTemplate<Suffix>}`
-    : Path;
-
-// @public (undocumented)
-export type PickOptionalKeys<
-  T extends {
-    [key: string]: any;
-  },
-> = {
-  [K in keyof T]: true extends T[K]['required'] ? never : K;
-}[keyof T];
-
-// @public (undocumented)
-export type PickRequiredKeys<
-  T extends {
-    [key: string]: any;
-  },
-> = {
-  [K in keyof T]: true extends T[K]['required'] ? K : never;
-}[keyof T];
-
-// @public (undocumented)
-export type Push<T extends any[], V> = [...T, V];
-
-// @public (undocumented)
-export interface QueryObject extends ParameterObject {
-  // (undocumented)
-  in: 'query';
-  // (undocumented)
-  style?: 'form' | 'deepObject' | 'pipeDelimited' | 'spaceDelimited';
-}
-
-// @public (undocumented)
-export type QuerySchema<
-  Doc extends RequiredDoc,
-  Path extends PathTemplate<Extract<keyof Doc['paths'], string>>,
-  Method extends DocPathMethod<Doc, Path>,
-> = ParametersSchema<Doc, DocPath<Doc, Path>, Method, ImmutableQueryObject>;
-
-// @public (undocumented)
-export type RequestBody<
-  Doc extends RequiredDoc,
-  Path extends Extract<keyof Doc['paths'], string>,
-  Method extends keyof Doc['paths'][Path],
-> = DocOperation<
-  Doc,
-  Path,
-  Method
->['requestBody'] extends ImmutableReferenceObject
-  ? 'requestBodies' extends ComponentTypes<Doc>
-    ? ComponentRef<
-        Doc,
-        'requestBodies',
-        DocOperation<Doc, Path, Method>['requestBody']
-      >
-    : never
-  : DocOperation<Doc, Path, Method>['requestBody'];
-
-// @public (undocumented)
-export type RequestBodySchema<
-  Doc extends RequiredDoc,
-  Path extends DocPathTemplate<Doc>,
-  Method extends DocPathMethod<Doc, Path>,
-> = RequestBody<
-  Doc,
-  DocPath<Doc, Path>,
-  Method
-> extends ImmutableRequestBodyObject
-  ? ObjectWithContentSchema<Doc, RequestBody<Doc, DocPath<Doc, Path>, Method>>
-  : never;
-
-// @public
-export type RequestBodyToJsonSchema<
-  Doc extends RequiredDoc,
-  Path extends PathTemplate<Extract<keyof Doc['paths'], string>>,
-  Method extends DocPathMethod<Doc, Path>,
-> = ToTypeSafe<RequestBodySchema<Doc, Path, Method>>;
-
-// @public
-export type RequiredDoc = Pick<ImmutableOpenAPIObject, 'paths' | 'components'>;
-
-// @public (undocumented)
-export type RequiredMap<
-  T extends {
-    [key: string]: any;
-  },
-> = {
-  [P in Exclude<PickRequiredKeys<T>, undefined>]: NonNullable<T[P]>;
-};
-
-// @public (undocumented)
-export type ResolveDocParameterSchema<
-  Doc extends RequiredDoc,
-  Schema extends ImmutableParameterObject['schema'],
-> = Schema extends ImmutableReferenceObject
-  ? 'parameters' extends ComponentTypes<Doc>
-    ? ComponentRef<Doc, 'parameters', Schema>
-    : never
-  : Schema;
-
-// @public (undocumented)
-type Response_2<
-  Doc extends RequiredDoc,
-  Path extends keyof Doc['paths'],
-  Method extends keyof Doc['paths'][Path],
-  StatusCode extends keyof Doc['paths'][Path]['responses'],
-> = DocOperation<
-  Doc,
-  Path,
-  Method
->['responses'][StatusCode] extends ImmutableReferenceObject
-  ? 'responses' extends ComponentTypes<Doc>
-    ? ComponentRef<
-        Doc,
-        'responses',
-        DocOperation<Doc, Path, Method>['responses'][StatusCode]
-      >
-    : never
-  : DocOperation<Doc, Path, Method>['responses'][StatusCode];
-export { Response_2 as Response };
-
-// @public
-export type ResponseBodyToJsonSchema<
-  Doc extends RequiredDoc,
-  Path extends PathTemplate<Extract<keyof Doc['paths'], string>>,
-  Method extends DocPathMethod<Doc, Path>,
-> = ToTypeSafe<ValueOf<ResponseSchemas<Doc, Path, Method>>>;
-
-// @public (undocumented)
-export type Responses<
-  Doc extends RequiredDoc,
-  Path extends keyof Doc['paths'],
-  Method extends keyof Doc['paths'][Path],
-> = {
-  [StatusCode in keyof DocOperation<
-    Doc,
-    Path,
-    Method
-  >['responses']]: Response_2<Doc, Path, Method, StatusCode>;
-};
-
-// @public (undocumented)
-export type ResponseSchema<
-  Doc extends RequiredDoc,
-  Object extends ImmutableResponseObject,
-> = ObjectWithContentSchema<Doc, Object>;
-
-// @public (undocumented)
-export type ResponseSchemas<
-  Doc extends RequiredDoc,
-  Path extends DocPathTemplate<Doc>,
-  Method extends DocPathMethod<Doc, Path>,
-> = {
-  [StatusCode in keyof Responses<Doc, DocPath<Doc, Path>, Method>]: Responses<
-    Doc,
-    DocPath<Doc, Path>,
-    Method
-  >[StatusCode] extends ImmutableResponseObject
-    ? ResponseSchema<
-        Doc,
-        Responses<Doc, DocPath<Doc, Path>, Method>[StatusCode]
-      >
-    : never;
-};
-
-// @public (undocumented)
-export type SchemaRef<Doc extends RequiredDoc, Schema> = Schema extends {
-  $ref: `#/components/schemas/${infer Name}`;
-}
-  ? 'schemas' extends keyof Doc['components']
-    ? Name extends keyof Doc['components']['schemas']
-      ? SchemaRef<Doc, Doc['components']['schemas'][Name]>
-      : never
-    : never
-  : {
-      [Key in keyof Schema]: SchemaRef<Doc, Schema[Key]>;
-    };
-
-// @public (undocumented)
-export type ToTypeSafe<T> = UnknownIfNever<ConvertAll<TuplifyUnion<T>>[number]>;
-
-// @public (undocumented)
-export type TuplifyUnion<
-  T,
-  L = LastOf<T>,
-  N = [T] extends [never] ? true : false,
-> = true extends N ? [] : Push<TuplifyUnion<Exclude<T, L>>, L>;
-
-// @public
-export type UnionToIntersection<U> = (
-  U extends any ? (k: U) => void : never
-) extends (k: infer I) => void
-  ? I
-  : never;
-
-// @public (undocumented)
-export type UnknownIfNever<P> = [P] extends [never] ? unknown : P;
-
-// @public
-export type ValueOf<T> = T[keyof T];
+export namespace core {}
 ```
diff --git a/plugins/openapi-utils/package.json b/plugins/openapi-utils/package.json
index f813c268da..a9131e0e8c 100644
--- a/plugins/openapi-utils/package.json
+++ b/plugins/openapi-utils/package.json
@@ -31,7 +31,7 @@
   ],
   "dependencies": {
     "@types/express": "^4.17.6",
-    "@types/express-serve-static-core": "^4.17.33",
+    "@types/express-serve-static-core": "^4.17.5",
     "express": "^4.17.1",
     "express-promise-router": "^4.1.0",
     "json-schema-to-ts": "^2.6.2",
diff --git a/plugins/openapi-utils/src/example.ts b/plugins/openapi-utils/src/example.ts
deleted file mode 100644
index 9aa3047b28..0000000000
--- a/plugins/openapi-utils/src/example.ts
+++ /dev/null
@@ -1,50 +0,0 @@
-/*
- * Copyright 2023 The Backstage Authors
- *
- * Licensed under the Apache License, Version 2.0 (the "License");
- * you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- *     http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
- */
-import express from 'express';
-import Router from 'express-promise-router';
-import { ApiRouter } from './router';
-import doc from './schema/petstore';
-
-interface RouterOptions {}
-
-export async function createRouter(
-  options: RouterOptions,
-): Promise<express.Router> {
-  console.log(options);
-  const router = Router() as ApiRouter<typeof doc>;
-
-  router.get('/pets/:petId', (_, res) => {
-    res.json({
-      id: 1,
-      name: 'test',
-    });
-  });
-
-  router.get('/pets', (_, res) => {
-    res.json([
-      {
-        id: 1,
-        tag: '123',
-        name: 'test',
-      },
-    ]);
-  });
-
-  router.post('/pets', (_, res) => {
-    res.send();
-  });
-  return router;
-}
diff --git a/plugins/openapi-utils/src/router.ts b/plugins/openapi-utils/src/router.ts
index 15f4fe9b7a..de2dc5b72a 100644
--- a/plugins/openapi-utils/src/router.ts
+++ b/plugins/openapi-utils/src/router.ts
@@ -14,26 +14,26 @@
  * limitations under the License.
  */
 import { Router } from 'express';
-import { RequiredDoc, DocRequestMatcher } from './types';
+import { core } from './types';
 
 /**
  * Typed Express router based on an OpenAPI 3.1 spec.
  * @public
  */
-export interface ApiRouter<Doc extends RequiredDoc> extends Router {
-  get: DocRequestMatcher<Doc, this, 'get'>;
+export interface ApiRouter<Doc extends core.Spec> extends Router {
+  get: core.RequestMatcher<Doc, this, 'get'>;
 
-  post: DocRequestMatcher<Doc, this, 'post'>;
+  post: core.RequestMatcher<Doc, this, 'post'>;
 
-  all: DocRequestMatcher<Doc, this, 'all'>;
+  all: core.RequestMatcher<Doc, this, 'all'>;
 
-  put: DocRequestMatcher<Doc, this, 'put'>;
+  put: core.RequestMatcher<Doc, this, 'put'>;
 
-  delete: DocRequestMatcher<Doc, this, 'delete'>;
+  delete: core.RequestMatcher<Doc, this, 'delete'>;
 
-  patch: DocRequestMatcher<Doc, this, 'patch'>;
+  patch: core.RequestMatcher<Doc, this, 'patch'>;
 
-  options: DocRequestMatcher<Doc, this, 'options'>;
+  options: core.RequestMatcher<Doc, this, 'options'>;
 
-  head: DocRequestMatcher<Doc, this, 'head'>;
+  head: core.RequestMatcher<Doc, this, 'head'>;
 }
diff --git a/plugins/openapi-utils/src/schema/petstore.ts b/plugins/openapi-utils/src/schema/petstore.ts
deleted file mode 100644
index a79a3efe4d..0000000000
--- a/plugins/openapi-utils/src/schema/petstore.ts
+++ /dev/null
@@ -1,183 +0,0 @@
-/*
- * Copyright 2023 The Backstage Authors
- *
- * Licensed under the Apache License, Version 2.0 (the "License");
- * you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- *     http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
- */
-export default {
-  openapi: '3.1.0',
-  info: {
-    version: '1.0.0',
-    title: 'Swagger Petstore',
-    license: {
-      name: 'MIT',
-      url: 'https://opensource.org/licenses/MIT',
-    },
-  },
-  servers: [
-    {
-      url: 'http://petstore.swagger.io/v1',
-    },
-  ],
-  paths: {
-    '/pets': {
-      get: {
-        summary: 'List all pets',
-        operationId: 'listPets',
-        tags: ['pets'],
-        parameters: [
-          {
-            name: 'limit',
-            in: 'query',
-            description: 'How many items to return at one time (max 100)',
-            required: false,
-            schema: {
-              type: 'integer',
-              format: 'int32',
-            },
-          },
-        ],
-        responses: {
-          '200': {
-            description: 'A paged array of pets',
-            headers: {
-              'x-next': {
-                description: 'A link to the next page of responses',
-                schema: {
-                  type: 'string',
-                },
-              },
-            },
-            content: {
-              'application/json': {
-                schema: {
-                  $ref: '#/components/schemas/Pets',
-                },
-              },
-            },
-          },
-          default: {
-            description: 'unexpected error',
-            content: {
-              'application/json': {
-                schema: {
-                  $ref: '#/components/schemas/Error',
-                },
-              },
-            },
-          },
-        },
-      },
-      post: {
-        summary: 'Create a pet',
-        operationId: 'createPets',
-        tags: ['pets'],
-        responses: {
-          '201': {
-            description: 'Null response',
-          },
-          default: {
-            description: 'unexpected error',
-            content: {
-              'application/json': {
-                schema: {
-                  $ref: '#/components/schemas/Error',
-                },
-              },
-            },
-          },
-        },
-      },
-    },
-    '/pets/{petId}': {
-      get: {
-        summary: 'Info for a specific pet',
-        operationId: 'showPetById',
-        tags: ['pets'],
-        parameters: [
-          {
-            name: 'petId',
-            in: 'path',
-            required: true,
-            description: 'The id of the pet to retrieve',
-            schema: {
-              type: 'string',
-            },
-          },
-        ],
-        responses: {
-          '200': {
-            description: 'Expected response to a valid request',
-            content: {
-              'application/json': {
-                schema: {
-                  $ref: '#/components/schemas/Pet',
-                },
-              },
-            },
-          },
-          default: {
-            description: 'unexpected error',
-            content: {
-              'application/json': {
-                schema: {
-                  $ref: '#/components/schemas/Error',
-                },
-              },
-            },
-          },
-        },
-      },
-    },
-  },
-  components: {
-    schemas: {
-      Pet: {
-        type: 'object',
-        required: ['id', 'name'],
-        properties: {
-          id: {
-            type: 'integer',
-            format: 'int64',
-          },
-          name: {
-            type: 'string',
-          },
-          tag: {
-            type: 'string',
-          },
-        },
-        additionalProperties: false,
-      },
-      Pets: {
-        type: 'array',
-        items: {
-          $ref: '#/components/schemas/Pet',
-        },
-      },
-      Error: {
-        type: 'object',
-        required: ['code', 'message'],
-        properties: {
-          code: {
-            type: 'integer',
-            format: 'int32',
-          },
-          message: {
-            type: 'string',
-          },
-        },
-        additionalProperties: false,
-      },
-    },
-  },
-} as const;
diff --git a/plugins/openapi-utils/src/types/common.ts b/plugins/openapi-utils/src/types/common.ts
index 50ed6e03cd..aea8ae2543 100644
--- a/plugins/openapi-utils/src/types/common.ts
+++ b/plugins/openapi-utils/src/types/common.ts
@@ -27,20 +27,13 @@ import {
 
 /**
  * Basic OpenAPI spec with paths and components properties enforced.
- *
- * @public
  */
 export type RequiredDoc = Pick<ImmutableOpenAPIObject, 'paths' | 'components'>;
 
-/**
- * @public
- */
 export type PathDoc = Pick<ImmutableOpenAPIObject, 'paths'>;
 
 /**
- * Get value types of `T`
- *
- * @public
+ * Get value types of `T`.
  */
 export type ValueOf<T> = T[keyof T];
 
@@ -49,13 +42,9 @@ export type ValueOf<T> = T[keyof T];
  *
  * @example
  * ```ts
- * const path = PathTemplate<"/posts/{postId}/comments/{commentId}"> = "/posts/1/comments/2"const pathWithParams: PathTemplate<"/posts/{postId}/comments/{commentId}"> = "/posts/1/comments/2";
+ * const path: PathTemplate<"/posts/{postId}/comments/{commentId}"> = "/posts/:postId/comments/:commentId";
  * const pathWithoutParams: PathTemplate<"/posts/comments"> = "/posts/comments";
  * ```
- *
- *
- *
- * @public
  */
 export type PathTemplate<Path extends string> =
   Path extends `${infer Prefix}{${infer PathName}}${infer Suffix}`
@@ -72,11 +61,9 @@ export type PathTemplate<Path extends string> =
  *       "/posts/comments": {},
  *   }
  * };
- * const specPathWithParams: DocPath<typeof spec, "/posts/1/comments/2"> = "/posts/{postId}/comments/{commentId}";
+ * const specPathWithParams: DocPath<typeof spec, "/posts/:postId/comments/:commentId"> = "/posts/{postId}/comments/{commentId}";
  * const specPathWithoutParams: DocPath<typeof spec, "/posts/comments"> = "/posts/comments";
  * ```
- *
- * @public
  */
 export type DocPath<
   Doc extends PathDoc,
@@ -88,24 +75,15 @@ export type DocPath<
   >]: Path extends PathTemplate<Template> ? Template : never;
 }>;
 
-/**
- * @public
- */
 export type DocPathTemplate<Doc extends PathDoc> = PathTemplate<
   Extract<keyof Doc['paths'], string>
 >;
 
-/**
- * @public
- */
 export type DocPathMethod<
   Doc extends Pick<RequiredDoc, 'paths'>,
   Path extends DocPathTemplate<Doc>,
 > = keyof Doc['paths'][DocPath<Doc, Path>];
 
-/**
- * @public
- */
 export type MethodAwareDocPath<
   Doc extends PathDoc,
   Path extends PathTemplate<Extract<keyof Doc['paths'], string>>,
@@ -121,26 +99,17 @@ export type MethodAwareDocPath<
     : never;
 }>;
 
-/**
- * @public
- */
 export type DocOperation<
   Doc extends RequiredDoc,
   Path extends keyof Doc['paths'],
   Method extends keyof Doc['paths'][Path],
 > = Doc['paths'][Path][Method];
 
-/**
- * @public
- */
 export type ComponentTypes<Doc extends RequiredDoc> = Extract<
   keyof Doc['components'],
   string
 >;
 
-/**
- * @public
- */
 export type ComponentRef<
   Doc extends RequiredDoc,
   Type extends ComponentTypes<Doc>,
@@ -153,9 +122,6 @@ export type ComponentRef<
     : never
   : never;
 
-/**
- * @public
- */
 export type SchemaRef<Doc extends RequiredDoc, Schema> = Schema extends {
   $ref: `#/components/schemas/${infer Name}`;
 }
@@ -166,9 +132,6 @@ export type SchemaRef<Doc extends RequiredDoc, Schema> = Schema extends {
     : never
   : { [Key in keyof Schema]: SchemaRef<Doc, Schema[Key]> };
 
-/**
- * @public
- */
 export type ObjectWithContentSchema<
   Doc extends RequiredDoc,
   Object extends { content?: ImmutableContentObject },
@@ -180,7 +143,6 @@ export type ObjectWithContentSchema<
  * From {@link https://stackoverflow.com/questions/71393738/typescript-intersection-not-union-type-from-json-schema}
  *
  * StackOverflow says not to do this, but union types aren't possible any other way.
- * @public
  */
 export type UnionToIntersection<U> = (
   U extends any ? (k: U) => void : never
@@ -188,32 +150,20 @@ export type UnionToIntersection<U> = (
   ? I
   : never;
 
-/**
- * @public
- */
 export type LastOf<T> = UnionToIntersection<
   T extends any ? () => T : never
 > extends () => infer R
   ? R
   : never;
 
-/**
- * @public
- */
 export type Push<T extends any[], V> = [...T, V];
 
-/**
- * @public
- */
 export type TuplifyUnion<
   T,
   L = LastOf<T>,
   N = [T] extends [never] ? true : false,
 > = true extends N ? [] : Push<TuplifyUnion<Exclude<T, L>>, L>;
 
-/**
- * @public
- */
 export type ConvertAll<T, R extends ReadonlyArray<unknown> = []> = T extends [
   infer First extends JSONSchema7,
   ...infer Rest,
@@ -221,27 +171,15 @@ export type ConvertAll<T, R extends ReadonlyArray<unknown> = []> = T extends [
   ? ConvertAll<Rest, [...R, FromSchema<First>]>
   : R;
 
-/**
- * @public
- */
 export type UnknownIfNever<P> = [P] extends [never] ? unknown : P;
 
-/**
- * @public
- */
 export type ToTypeSafe<T> = UnknownIfNever<ConvertAll<TuplifyUnion<T>>[number]>;
 
-/**
- * @public
- */
 export type DiscriminateUnion<T, K extends keyof T, V extends T[K]> = Extract<
   T,
   Record<K, V>
 >;
 
-/**
- * @public
- */
 export type MapDiscriminatedUnion<
   T extends Record<K, string>,
   K extends keyof T,
@@ -249,41 +187,23 @@ export type MapDiscriminatedUnion<
   [V in T[K]]: DiscriminateUnion<T, K, V>;
 };
 
-/**
- * @public
- */
 export type PickOptionalKeys<T extends { [key: string]: any }> = {
   [K in keyof T]: true extends T[K]['required'] ? never : K;
 }[keyof T];
 
-/**
- * @public
- */
 export type PickRequiredKeys<T extends { [key: string]: any }> = {
   [K in keyof T]: true extends T[K]['required'] ? K : never;
 }[keyof T];
 
-/**
- * @public
- */
 export type OptionalMap<T extends { [key: string]: any }> = {
   [P in Exclude<PickOptionalKeys<T>, undefined>]?: NonNullable<T[P]>;
 };
 
-/**
- * @public
- */
 export type RequiredMap<T extends { [key: string]: any }> = {
   [P in Exclude<PickRequiredKeys<T>, undefined>]: NonNullable<T[P]>;
 };
 
-/**
- * @public
- */
 export type FullMap<T extends { [key: string]: any }> = RequiredMap<T> &
   OptionalMap<T>;
 
-/**
- * @public
- */
 export type Filter<T, U> = T extends U ? T : never;
diff --git a/plugins/openapi-utils/src/types/express.ts b/plugins/openapi-utils/src/types/express.ts
index 87b91c6c7c..1ab262352d 100644
--- a/plugins/openapi-utils/src/types/express.ts
+++ b/plugins/openapi-utils/src/types/express.ts
@@ -19,19 +19,10 @@ import { PathSchema, QuerySchema } from './params';
 import { RequestBodyToJsonSchema } from './requests';
 import { ResponseBodyToJsonSchema } from './responses';
 
-/**
- * Pulled from the express library.
- * @public
- */
-export interface ParsedQs {
-  [key: string]: undefined | string | string[] | ParsedQs | ParsedQs[];
-}
-
 /**
  * Typed express request handler.
- * @public
  */
-export type DocRequestHandler<
+type DocRequestHandler<
   Doc extends RequiredDoc,
   Path extends DocPathTemplate<Doc>,
   Method extends keyof Doc['paths'][Path],
@@ -45,9 +36,8 @@ export type DocRequestHandler<
 
 /**
  * Typed express error handler / request handler union type.
- * @public
  */
-export type DocRequestHandlerParams<
+type DocRequestHandlerParams<
   Doc extends RequiredDoc,
   Path extends DocPathTemplate<Doc>,
   Method extends keyof Doc['paths'][Path],
@@ -61,7 +51,6 @@ export type DocRequestHandlerParams<
 
 /**
  * Superset of the express router path matcher that enforces typed request and response bodies.
- * @public
  */
 export interface DocRequestMatcher<
   Doc extends RequiredDoc,
diff --git a/plugins/openapi-utils/src/types/immutable.ts b/plugins/openapi-utils/src/types/immutable.ts
index 5056512054..400d4e4b4b 100644
--- a/plugins/openapi-utils/src/types/immutable.ts
+++ b/plugins/openapi-utils/src/types/immutable.ts
@@ -31,7 +31,6 @@ import type {
 /**
  * From {@link https://github.com/microsoft/TypeScript/issues/13923#issuecomment-653675557}, allows
  *  us to convert from `as const` to the various OpenAPI types documented in `openapi3-ts`.
- * @public
  */
 export type Immutable<T> = T extends
   | Function
@@ -47,94 +46,46 @@ export type Immutable<T> = T extends
   ? ReadonlySet<Immutable<S>>
   : { readonly [P in keyof T]: Immutable<T[P]> };
 
-/**
- * @public
- */
 export type ImmutableObject<T> = { readonly [K in keyof T]: Immutable<T[K]> };
 
-/**
- * @public
- */
 export type ImmutableReferenceObject = ImmutableObject<ReferenceObject>;
 
-/**
- * @public
- */
 export type ImmutableOpenAPIObject = ImmutableObject<OpenAPIObject>;
 
-/**
- * @public
- */
 export type ImmutableContentObject = ImmutableObject<ContentObject>;
 
-/**
- * @public
- */
 export type ImmutableRequestBodyObject = ImmutableObject<RequestBodyObject>;
 
-/**
- * @public
- */
 export type ImmutableResponseObject = ImmutableObject<ResponseObject>;
 
-/**
- * @public
- */
 export type ImmutableParameterObject = ImmutableObject<ParameterObject>;
 
-/**
- * @public
- */
-export interface HeaderObject extends ParameterObject {
+interface HeaderObject extends ParameterObject {
   in: 'header';
   style: 'simple';
 }
 
-/**
- * @public
- */
 export type ImmutableHeaderObject = ImmutableObject<HeaderObject>;
 
-/**
- * @public
- */
-export interface CookieObject extends ParameterObject {
+interface CookieObject extends ParameterObject {
   in: 'cookie';
   style?: 'form';
 }
 
-/**
- * @public
- */
 export type ImmutableCookieObject = ImmutableObject<CookieObject>;
 
-/**
- * @public
- */
-export interface QueryObject extends ParameterObject {
+interface QueryObject extends ParameterObject {
   in: 'query';
   style?: 'form' | 'deepObject' | 'pipeDelimited' | 'spaceDelimited';
 }
 
-/**
- * @public
- */
 export type ImmutableQueryObject = ImmutableObject<QueryObject>;
 
-/**
- * @public
- */
-export interface PathObject extends ParameterObject {
+interface PathObject extends ParameterObject {
   in: 'path';
   style?: 'simple' | 'label' | 'matrix';
 }
 
-/**
- * @public
- */
 export type ImmutablePathObject = ImmutableObject<PathObject>;
 
-/**
- * @public
- */
 export type ImmutableSchemaObject = ImmutableObject<SchemaObject>;
diff --git a/plugins/openapi-utils/src/types/index.ts b/plugins/openapi-utils/src/types/index.ts
index e656e1967c..5fcd90d558 100644
--- a/plugins/openapi-utils/src/types/index.ts
+++ b/plugins/openapi-utils/src/types/index.ts
@@ -13,9 +13,33 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-export * from './common';
-export * from './express';
-export * from './requests';
-export * from './responses';
-export * from './immutable';
-export * from './params';
+
+import type { RequiredDoc } from './common';
+import type { DocRequestMatcher } from './express';
+
+/**
+ * @public
+ */
+export namespace core {
+  /**
+   * @internal
+   */
+  export type Spec = RequiredDoc;
+
+  /**
+   * @internal
+   */
+  export type RequestMatcher<
+    Doc extends RequiredDoc,
+    T,
+    Method extends
+      | 'all'
+      | 'get'
+      | 'post'
+      | 'put'
+      | 'delete'
+      | 'patch'
+      | 'options'
+      | 'head',
+  > = DocRequestMatcher<Doc, T, Method>;
+}
diff --git a/plugins/openapi-utils/src/types/params.ts b/plugins/openapi-utils/src/types/params.ts
index dce743e6e8..1a75775aab 100644
--- a/plugins/openapi-utils/src/types/params.ts
+++ b/plugins/openapi-utils/src/types/params.ts
@@ -37,10 +37,7 @@ import {
 } from './common';
 import { FromSchema, JSONSchema7 } from 'json-schema-to-ts';
 
-/**
- * @public
- */
-export type DocParameter<
+type DocParameter<
   Doc extends RequiredDoc,
   Path extends Extract<keyof Doc['paths'], string>,
   Method extends keyof Doc['paths'][Path],
@@ -59,10 +56,7 @@ export type DocParameter<
     : never
   : DocOperation<Doc, Path, Method>['parameters'][Parameter];
 
-/**
- * @public
- */
-export type DocParameters<
+type DocParameters<
   Doc extends RequiredDoc,
   Path extends Extract<keyof Doc['paths'], string>,
   Method extends keyof Doc['paths'][Path],
@@ -76,10 +70,7 @@ export type DocParameters<
     }
   : never;
 
-/**
- * @public
- */
-export type ResolveDocParameterSchema<
+type ResolveDocParameterSchema<
   Doc extends RequiredDoc,
   Schema extends ImmutableParameterObject['schema'],
 > = Schema extends ImmutableReferenceObject
@@ -88,10 +79,7 @@ export type ResolveDocParameterSchema<
     : never
   : Schema;
 
-/**
- * @public
- */
-export type ParameterSchema<
+type ParameterSchema<
   Doc extends RequiredDoc,
   Schema extends ImmutableParameterObject['schema'],
 > = ResolveDocParameterSchema<Doc, Schema> extends infer R
@@ -102,10 +90,7 @@ export type ParameterSchema<
     : never
   : never;
 
-/**
- * @public
- */
-export type MapToSchema<
+type MapToSchema<
   Doc extends RequiredDoc,
   T extends Record<string, ImmutableParameterObject>,
 > = {
@@ -114,10 +99,7 @@ export type MapToSchema<
     : never;
 };
 
-/**
- * @public
- */
-export type ParametersSchema<
+type ParametersSchema<
   Doc extends RequiredDoc,
   Path extends Extract<keyof Doc['paths'], string>,
   Method extends keyof Doc['paths'][Path],
@@ -134,36 +116,24 @@ export type ParametersSchema<
     >
   : never;
 
-/**
- * @public
- */
 export type HeaderSchema<
   Doc extends RequiredDoc,
   Path extends PathTemplate<Extract<keyof Doc['paths'], string>>,
   Method extends DocPathMethod<Doc, Path>,
 > = ParametersSchema<Doc, DocPath<Doc, Path>, Method, ImmutableHeaderObject>;
 
-/**
- * @public
- */
 export type CookieSchema<
   Doc extends RequiredDoc,
   Path extends PathTemplate<Extract<keyof Doc['paths'], string>>,
   Method extends DocPathMethod<Doc, Path>,
 > = ParametersSchema<Doc, DocPath<Doc, Path>, Method, ImmutableCookieObject>;
 
-/**
- * @public
- */
 export type PathSchema<
   Doc extends RequiredDoc,
   Path extends PathTemplate<Extract<keyof Doc['paths'], string>>,
   Method extends DocPathMethod<Doc, Path>,
 > = ParametersSchema<Doc, DocPath<Doc, Path>, Method, ImmutablePathObject>;
 
-/**
- * @public
- */
 export type QuerySchema<
   Doc extends RequiredDoc,
   Path extends PathTemplate<Extract<keyof Doc['paths'], string>>,
diff --git a/plugins/openapi-utils/src/types/requests.ts b/plugins/openapi-utils/src/types/requests.ts
index e6542e186d..71e25b91bd 100644
--- a/plugins/openapi-utils/src/types/requests.ts
+++ b/plugins/openapi-utils/src/types/requests.ts
@@ -35,10 +35,7 @@ import {
   ImmutableRequestBodyObject,
 } from './immutable';
 
-/**
- * @public
- */
-export type RequestBody<
+type RequestBody<
   Doc extends RequiredDoc,
   Path extends Extract<keyof Doc['paths'], string>,
   Method extends keyof Doc['paths'][Path],
@@ -56,10 +53,7 @@ export type RequestBody<
     : never
   : DocOperation<Doc, Path, Method>['requestBody'];
 
-/**
- * @public
- */
-export type RequestBodySchema<
+type RequestBodySchema<
   Doc extends RequiredDoc,
   Path extends DocPathTemplate<Doc>,
   Method extends DocPathMethod<Doc, Path>,
@@ -73,7 +67,6 @@ export type RequestBodySchema<
 
 /**
  * Transform the OpenAPI request body schema to a typesafe JSON schema.
- * @public
  */
 export type RequestBodyToJsonSchema<
   Doc extends RequiredDoc,
diff --git a/plugins/openapi-utils/src/types/responses.ts b/plugins/openapi-utils/src/types/responses.ts
index c623b44333..ef60fb873f 100644
--- a/plugins/openapi-utils/src/types/responses.ts
+++ b/plugins/openapi-utils/src/types/responses.ts
@@ -33,10 +33,7 @@ import type {
 } from './common';
 import { ImmutableReferenceObject, ImmutableResponseObject } from './immutable';
 
-/**
- * @public
- */
-export type Response<
+type Response<
   Doc extends RequiredDoc,
   Path extends keyof Doc['paths'],
   Method extends keyof Doc['paths'][Path],
@@ -55,10 +52,7 @@ export type Response<
     : never
   : DocOperation<Doc, Path, Method>['responses'][StatusCode];
 
-/**
- * @public
- */
-export type Responses<
+type Responses<
   Doc extends RequiredDoc,
   Path extends keyof Doc['paths'],
   Method extends keyof Doc['paths'][Path],
@@ -71,18 +65,12 @@ export type Responses<
   >;
 };
 
-/**
- * @public
- */
-export type ResponseSchema<
+type ResponseSchema<
   Doc extends RequiredDoc,
   Object extends ImmutableResponseObject,
 > = ObjectWithContentSchema<Doc, Object>;
 
-/**
- * @public
- */
-export type ResponseSchemas<
+type ResponseSchemas<
   Doc extends RequiredDoc,
   Path extends DocPathTemplate<Doc>,
   Method extends DocPathMethod<Doc, Path>,
@@ -101,7 +89,6 @@ export type ResponseSchemas<
 
 /**
  * Transform the OpenAPI request body schema to a typesafe JSON schema.
- * @public
  */
 export type ResponseBodyToJsonSchema<
   Doc extends RequiredDoc,
diff --git a/yarn.lock b/yarn.lock
index 61e2f01c05..10ce468f7c 100644
--- a/yarn.lock
+++ b/yarn.lock
@@ -3833,7 +3833,7 @@ __metadata:
   dependencies:
     "@backstage/cli": "workspace:^"
     "@types/express": ^4.17.6
-    "@types/express-serve-static-core": ^4.17.33
+    "@types/express-serve-static-core": ^4.17.5
     express: ^4.17.1
     express-promise-router: ^4.1.0
     json-schema-to-ts: ^2.6.2
@@ -15804,17 +15804,6 @@ __metadata:
   languageName: node
   linkType: hard
 
-"@types/express-serve-static-core@npm:*, @types/express-serve-static-core@npm:^4.17.18, @types/express-serve-static-core@npm:^4.17.31, @types/express-serve-static-core@npm:^4.17.33, @types/express-serve-static-core@npm:^4.17.5":
-  version: 4.17.33
-  resolution: "@types/express-serve-static-core@npm:4.17.33"
-  dependencies:
-    "@types/node": "*"
-    "@types/qs": "*"
-    "@types/range-parser": "*"
-  checksum: dce580d16b85f207445af9d4053d66942b27d0c72e86153089fa00feee3e96ae336b7bedb31ed4eea9e553c99d6dd356ed6e0928f135375d9f862a1a8015adf2
-  languageName: node
-  linkType: hard
-
 "@types/express-serve-static-core@npm:*, @types/express-serve-static-core@npm:^4.17.30, @types/express-serve-static-core@npm:^4.17.31, @types/express-serve-static-core@npm:^4.17.5":
   version: 4.17.33
   resolution: "@types/express-serve-static-core@npm:4.17.33"
@@ -15868,18 +15857,6 @@ __metadata:
   languageName: node
   linkType: hard
 
-"@types/express@npm:4.17.14":
-  version: 4.17.14
-  resolution: "@types/express@npm:4.17.14"
-  dependencies:
-    "@types/body-parser": "*"
-    "@types/express-serve-static-core": ^4.17.18
-    "@types/qs": "*"
-    "@types/serve-static": "*"
-  checksum: 15c1af46d02de834e4a225eccaa9d85c0370fdbb3ed4e1bc2d323d24872309961542b993ae236335aeb3e278630224a6ea002078d39e651d78a3b0356b1eaa79
-  languageName: node
-  linkType: hard
-
 "@types/fs-extra@npm:^9.0.1, @types/fs-extra@npm:^9.0.3, @types/fs-extra@npm:^9.0.5, @types/fs-extra@npm:^9.0.6":
   version: 9.0.13
   resolution: "@types/fs-extra@npm:9.0.13"
@@ -20732,13 +20709,6 @@ __metadata:
   languageName: node
   linkType: hard
 
-"content-type@npm:~1.0.4":
-  version: 1.0.4
-  resolution: "content-type@npm:1.0.4"
-  checksum: 3d93585fda985d1554eca5ebd251994327608d2e200978fdbfba21c0c679914d5faf266d17027de44b34a72c7b0745b18584ecccaa7e1fdfb6a68ac7114f12e0
-  languageName: node
-  linkType: hard
-
 "content-type@npm:~1.0.4, content-type@npm:~1.0.5":
   version: 1.0.5
   resolution: "content-type@npm:1.0.5"
@@ -38831,20 +38801,6 @@ __metadata:
   languageName: node
   linkType: hard
 
-"ts-log@npm:^2.1.4":
-  version: 2.2.5
-  resolution: "ts-log@npm:2.2.5"
-  checksum: 28f78ab15b8555d56c089dbc243327d8ce4331219956242a29fc4cb3bad6bb0cb8234dd17a292381a1b1dba99a7e4849a2181b2e1a303e8247e9f4ca4e284f2d
-  languageName: node
-  linkType: hard
-
-"ts-log@npm:^2.1.4, ts-log@npm:^2.2.3":
-  version: 2.2.5
-  resolution: "ts-log@npm:2.2.5"
-  checksum: 28f78ab15b8555d56c089dbc243327d8ce4331219956242a29fc4cb3bad6bb0cb8234dd17a292381a1b1dba99a7e4849a2181b2e1a303e8247e9f4ca4e284f2d
-  languageName: node
-  linkType: hard
-
 "ts-log@npm:^2.2.3":
   version: 2.2.3
   resolution: "ts-log@npm:2.2.3"

From 6a985600a718f98f54acd145cb705ae64c957f54 Mon Sep 17 00:00:00 2001
From: Aramis Sennyey <sennyeya@amazon.com>
Date: Thu, 16 Mar 2023 12:37:29 -0400
Subject: [PATCH 50/61] Add CLI command for full repo check.

Signed-off-by: Aramis Sennyey <sennyeya@amazon.com>
---
 packages/cli/package.json                     |  1 +
 packages/cli/src/commands/index.ts            |  7 ++
 packages/cli/src/commands/openapi/generate.ts | 86 +++++++++++++++----
 packages/cli/src/commands/openapi/verify.ts   | 51 ++++++-----
 plugins/catalog-backend/schema/openapi.ts     |  2 +-
 yarn.lock                                     |  1 +
 6 files changed, 110 insertions(+), 38 deletions(-)

diff --git a/packages/cli/package.json b/packages/cli/package.json
index 8f166db53d..cc1d0a4d1c 100644
--- a/packages/cli/package.json
+++ b/packages/cli/package.json
@@ -106,6 +106,7 @@
     "node-libs-browser": "^2.2.1",
     "npm-packlist": "^5.0.0",
     "ora": "^5.3.0",
+    "p-limit": "^3.0.2",
     "postcss": "^8.1.0",
     "process": "^0.11.10",
     "react-dev-utils": "^12.0.0-next.60",
diff --git a/packages/cli/src/commands/index.ts b/packages/cli/src/commands/index.ts
index 6c29741060..713863b685 100644
--- a/packages/cli/src/commands/index.ts
+++ b/packages/cli/src/commands/index.ts
@@ -87,6 +87,13 @@ export function registerRepoCommand(program: Command) {
     )
     .action(lazy(() => import('./openapi/verify').then(m => m.bulkCommand)));
 
+  command
+    .command('schema:openapi:generate')
+    .description(
+      'Generates a Typescript file from an OpenAPI yaml spec. For use with the `@backstage/backend-openapi-utils` ApiRouter type.',
+    )
+    .action(lazy(() => import('./openapi/generate').then(m => m.bulkCommand)));
+
   command
     .command('test')
     .allowUnknownOption(true) // Allows the command to run, but we still need to parse raw args
diff --git a/packages/cli/src/commands/openapi/generate.ts b/packages/cli/src/commands/openapi/generate.ts
index f90f152b09..14a1217b7b 100644
--- a/packages/cli/src/commands/openapi/generate.ts
+++ b/packages/cli/src/commands/openapi/generate.ts
@@ -17,25 +17,81 @@
 import fs from 'fs-extra';
 import { paths } from '../../lib/paths';
 import YAML from 'js-yaml';
+import chalk from 'chalk';
+import { resolve } from 'path';
+import { PackageGraph } from '../../lib/monorepo';
+import pLimit from 'p-limit';
+import { relative as relativePath } from 'path';
+
+async function generate(
+  directoryPath: string,
+  config?: { skipMissingYamlFile: boolean },
+) {
+  const { skipMissingYamlFile } = config ?? {};
+  const openapiPath = resolve(directoryPath, 'openapi.yaml');
+  if (!(await fs.pathExists(openapiPath))) {
+    if (skipMissingYamlFile) {
+      return;
+    }
+    throw new Error('Could not find openapi.yaml in root of directory.');
+  }
+  const yaml = YAML.load(await fs.readFile(openapiPath, 'utf8'));
+
+  // For now, we're not adding a header or linting after pasting.
+  await fs.writeFile(
+    resolve(directoryPath, 'schema/openapi.ts'),
+    `export default ${JSON.stringify(yaml, null, 2)} as const`,
+  );
+}
 
 export async function command() {
-  const openapiPath = paths.resolveTarget('openapi.yaml');
-  if (!(await fs.pathExists(openapiPath))) {
-    console.warn('Could not find openapi.yaml in root of directory.');
-    process.exit(1);
-  }
   try {
-    const yaml = YAML.load(
-      await fs.readFile(paths.resolveTarget('openapi.yaml'), 'utf8'),
-    );
-
-    // For now, we're not adding a header or linting after pasting.
-    await fs.writeFile(
-      paths.resolveTarget('schema/openapi.ts'),
-      `export default ${JSON.stringify(yaml, null, 2)} as const`,
-    );
+    await generate(paths.resolveTarget('.'));
+    console.log(chalk.green('OpenAPI files successfully generated.'));
   } catch (err) {
-    console.error(err);
+    console.error(chalk.red(err.message));
+    process.exit(1);
+  }
+}
+
+export async function bulkCommand(): Promise<void> {
+  const packages = await PackageGraph.listTargetPackages();
+  const limit = pLimit(5);
+
+  const resultsList = await Promise.all(
+    packages.map(pkg =>
+      limit(async () => {
+        let resultText = '';
+        try {
+          await generate(pkg.dir, { skipMissingYamlFile: true });
+        } catch (err) {
+          resultText = err.message;
+        }
+
+        return {
+          relativeDir: relativePath(paths.targetRoot, pkg.dir),
+          resultText,
+        };
+      }),
+    ),
+  );
+
+  let failed = false;
+  for (const { relativeDir, resultText } of resultsList) {
+    if (resultText) {
+      console.log();
+      console.log(
+        chalk.red(
+          `OpenAPI yaml to Typescript generation failed in ${relativeDir}:`,
+        ),
+      );
+      console.log(resultText.trimStart());
+
+      failed = true;
+    }
+  }
+
+  if (failed) {
     process.exit(1);
   }
 }
diff --git a/packages/cli/src/commands/openapi/verify.ts b/packages/cli/src/commands/openapi/verify.ts
index f93672aca9..ad0031622f 100644
--- a/packages/cli/src/commands/openapi/verify.ts
+++ b/packages/cli/src/commands/openapi/verify.ts
@@ -25,6 +25,7 @@ import { PackageGraph } from '../../lib/monorepo';
 import { cloneDeep } from 'lodash';
 import Parser from '@apidevtools/swagger-parser';
 import { detectRoleFromPackage } from '../../lib/role';
+import pLimit from 'p-limit';
 
 const SUPPORTED_ROLES = [
   'backend',
@@ -35,14 +36,15 @@ const SUPPORTED_ROLES = [
 
 async function verify(
   directoryPath: string,
-  { checkRole }: { checkRole: boolean },
+  config: { checkRole: boolean } = { checkRole: false },
 ) {
+  const { checkRole } = config ?? {};
   if (checkRole) {
     const role = detectRoleFromPackage(
       await fs.readJson(resolve(directoryPath, 'package.json')),
     );
 
-    if (!SUPPORTED_ROLES.some(r => r === role)) {
+    if (!role || !SUPPORTED_ROLES.includes(role)) {
       console.log(chalk.red(`Unsupported role ${role}`));
       process.exit(1);
     }
@@ -61,15 +63,17 @@ async function verify(
     throw new Error('No `schema/openapi.ts` file found.');
   }
   const schema = await import(join(directoryPath, 'schema/openapi'));
-  if (schema.default) {
-    if (!isEqual(schema.default, yaml)) {
-      throw new Error(
-        '`openapi.yaml` and `schema/openapi.ts` do not match. Please run `yarn build:openapi` to generate the `schema/openapi.ts` file from the `openapi.yaml` file.',
-      );
-    }
-  } else {
+  if (!schema.default) {
     throw new Error('`schemas/openapi.ts` needs to have a default export.');
   }
+  if (!isEqual(schema.default, yaml)) {
+    throw new Error(
+      `\`openapi.yaml\` and \`schema/openapi.ts\` do not match. Please run \`yarn --cwd ${relativePath(
+        paths.targetRoot,
+        directoryPath,
+      )} schema:openapi:generate\` to regenerate \`schema/openapi.ts\`.`,
+    );
+  }
 }
 
 export async function command() {
@@ -84,28 +88,31 @@ export async function command() {
 
 export async function bulkCommand(): Promise<void> {
   const packages = await PackageGraph.listTargetPackages();
+  const limit = pLimit(5);
 
   const resultsList = await Promise.all(
-    packages.map(async pkg => {
-      let resultText = '';
-      try {
-        await verify(pkg.dir, { checkRole: false });
-      } catch (err) {
-        resultText = err.message;
-      }
+    packages.map(pkg =>
+      limit(async () => {
+        let resultText = '';
+        try {
+          await verify(pkg.dir);
+        } catch (err) {
+          resultText = err.message;
+        }
 
-      return {
-        relativeDir: relativePath(paths.targetRoot, pkg.dir),
-        resultText,
-      };
-    }),
+        return {
+          relativeDir: relativePath(paths.targetRoot, pkg.dir),
+          resultText,
+        };
+      }),
+    ),
   );
 
   let failed = false;
   for (const { relativeDir, resultText } of resultsList) {
     if (resultText) {
       console.log();
-      console.log(chalk.red(`Lint failed in ${relativeDir}:`));
+      console.log(chalk.red(`OpenAPI validation failed in ${relativeDir}:`));
       console.log(resultText.trimStart());
 
       failed = true;
diff --git a/plugins/catalog-backend/schema/openapi.ts b/plugins/catalog-backend/schema/openapi.ts
index be58a2ea74..3d775c54cf 100644
--- a/plugins/catalog-backend/schema/openapi.ts
+++ b/plugins/catalog-backend/schema/openapi.ts
@@ -112,7 +112,7 @@ export default {
         required: false,
         schema: {
           type: 'integer',
-          minimum: 1,
+          minimum: 0,
         },
       },
       limit: {
diff --git a/yarn.lock b/yarn.lock
index 10ce468f7c..3697631867 100644
--- a/yarn.lock
+++ b/yarn.lock
@@ -4062,6 +4062,7 @@ __metadata:
     nodemon: ^2.0.2
     npm-packlist: ^5.0.0
     ora: ^5.3.0
+    p-limit: ^3.0.2
     postcss: ^8.1.0
     process: ^0.11.10
     react-dev-utils: ^12.0.0-next.60

From c62081e475e2f9f077f7bef8efd3f093a0fcb0ea Mon Sep 17 00:00:00 2001
From: Aramis Sennyey <sennyeya@amazon.com>
Date: Thu, 16 Mar 2023 13:10:22 -0400
Subject: [PATCH 51/61] Update yarn.lock.

Signed-off-by: Aramis Sennyey <sennyeya@amazon.com>
---
 packages/cli/cli-report.md | 10 ++++++++++
 1 file changed, 10 insertions(+)

diff --git a/packages/cli/cli-report.md b/packages/cli/cli-report.md
index 998f2f3665..fe536d4a23 100644
--- a/packages/cli/cli-report.md
+++ b/packages/cli/cli-report.md
@@ -424,6 +424,7 @@ Commands:
   clean
   list-deprecations [options]
   schema:openapi:verify
+  schema:openapi:generate
   test [options]
   help [command]
 ```
@@ -470,6 +471,15 @@ Options:
   -h, --help
 ```
 
+### `backstage-cli repo schema:openapi:generate`
+
+```
+Usage: backstage-cli repo schema:openapi:generate [options]
+
+Options:
+  -h, --help
+```
+
 ### `backstage-cli repo schema:openapi:verify`
 
 ```

From 53e6c46244add354273087cfcfdfb033259b7beb Mon Sep 17 00:00:00 2001
From: Aramis Sennyey <sennyeya@amazon.com>
Date: Thu, 16 Mar 2023 18:19:55 -0400
Subject: [PATCH 52/61] Update to devdependency.

Signed-off-by: Aramis Sennyey <sennyeya@amazon.com>
---
 plugins/openapi-utils/package.json | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/plugins/openapi-utils/package.json b/plugins/openapi-utils/package.json
index a9131e0e8c..5a06c48ffc 100644
--- a/plugins/openapi-utils/package.json
+++ b/plugins/openapi-utils/package.json
@@ -24,14 +24,14 @@
     "postpack": "backstage-cli package postpack"
   },
   "devDependencies": {
-    "@backstage/cli": "workspace:^"
+    "@backstage/cli": "workspace:^",
+    "@types/express-serve-static-core": "^4.17.5"
   },
   "files": [
     "dist"
   ],
   "dependencies": {
     "@types/express": "^4.17.6",
-    "@types/express-serve-static-core": "^4.17.5",
     "express": "^4.17.1",
     "express-promise-router": "^4.1.0",
     "json-schema-to-ts": "^2.6.2",

From 167434d0cc1d8b580ff51795bc8cc5ee7da62131 Mon Sep 17 00:00:00 2001
From: Aramis Sennyey <sennyeya@amazon.com>
Date: Fri, 17 Mar 2023 12:45:18 -0400
Subject: [PATCH 53/61] Move CLI tooling to repo-tools.

Signed-off-by: Aramis Sennyey <sennyeya@amazon.com>
---
 .changeset/fresh-lions-compete.md             |  2 +-
 .github/workflows/ci.yml                      |  2 +-
 packages/cli/cli-report.md                    | 40 ---------
 packages/cli/package.json                     |  3 -
 packages/cli/src/commands/index.ts            | 28 -------
 packages/repo-tools/cli-report.md             | 20 +++++
 packages/repo-tools/package.json              |  4 +
 .../src/commands/api-reports/api-reports.ts   | 28 +------
 packages/repo-tools/src/commands/index.ts     | 14 ++++
 .../src/commands/openapi/generate.ts          | 40 ++-------
 .../repo-tools/src/commands/openapi/runner.ts | 49 +++++++++++
 .../src/commands/openapi/verify.ts            | 81 ++++---------------
 packages/repo-tools/src/lib/paths.ts          | 36 +++++++++
 yarn.lock                                     |  7 +-
 14 files changed, 154 insertions(+), 200 deletions(-)
 rename packages/{cli => repo-tools}/src/commands/openapi/generate.ts (64%)
 create mode 100644 packages/repo-tools/src/commands/openapi/runner.ts
 rename packages/{cli => repo-tools}/src/commands/openapi/verify.ts (51%)

diff --git a/.changeset/fresh-lions-compete.md b/.changeset/fresh-lions-compete.md
index 906ed37665..76c2161c37 100644
--- a/.changeset/fresh-lions-compete.md
+++ b/.changeset/fresh-lions-compete.md
@@ -1,5 +1,5 @@
 ---
-'@backstage/cli': minor
+'@backstage/repo-tools': minor
 ---
 
 Adding two new commands to support OpenAPI spec writing, `schema:openapi:generate` to generate the Typescript file that `@backstage/backend-openapi-utils` needs for typing and `schema:openapi:verify` to verify that this file exists and matches your `openapi.yaml` file.
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index d7fb8c3d74..3788687ab2 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -93,7 +93,7 @@ jobs:
         run: node scripts/verify-api-reference.js
 
       - name: verify openapi.yaml matches schema/openapi.ts files
-        run: yarn backstage-cli repo schema:openapi:verify
+        run: yarn backstage-repo-tools schema:openapi:verify
 
       - name: verify doc links
         run: node scripts/verify-links.js
diff --git a/packages/cli/cli-report.md b/packages/cli/cli-report.md
index fe536d4a23..bad849d283 100644
--- a/packages/cli/cli-report.md
+++ b/packages/cli/cli-report.md
@@ -209,8 +209,6 @@ Commands:
   clean
   prepack
   postpack
-  schema:openapi:verify
-  schema:openapi:generate
   help [command]
 ```
 
@@ -267,24 +265,6 @@ Options:
   -h, --help
 ```
 
-### `backstage-cli package schema:openapi:generate`
-
-```
-Usage: backstage-cli package schema:openapi:generate [options]
-
-Options:
-  -h, --help
-```
-
-### `backstage-cli package schema:openapi:verify`
-
-```
-Usage: backstage-cli package schema:openapi:verify [options]
-
-Options:
-  -h, --help
-```
-
 ### `backstage-cli package start`
 
 ```
@@ -423,8 +403,6 @@ Commands:
   lint [options]
   clean
   list-deprecations [options]
-  schema:openapi:verify
-  schema:openapi:generate
   test [options]
   help [command]
 ```
@@ -471,24 +449,6 @@ Options:
   -h, --help
 ```
 
-### `backstage-cli repo schema:openapi:generate`
-
-```
-Usage: backstage-cli repo schema:openapi:generate [options]
-
-Options:
-  -h, --help
-```
-
-### `backstage-cli repo schema:openapi:verify`
-
-```
-Usage: backstage-cli repo schema:openapi:verify [options]
-
-Options:
-  -h, --help
-```
-
 ### `backstage-cli repo test`
 
 ```
diff --git a/packages/cli/package.json b/packages/cli/package.json
index cc1d0a4d1c..5974116843 100644
--- a/packages/cli/package.json
+++ b/packages/cli/package.json
@@ -30,7 +30,6 @@
     "backstage-cli": "bin/backstage-cli"
   },
   "dependencies": {
-    "@apidevtools/swagger-parser": "^10.1.0",
     "@backstage/cli-common": "workspace:^",
     "@backstage/config": "workspace:^",
     "@backstage/config-loader": "workspace:^",
@@ -97,7 +96,6 @@
     "jest-css-modules": "^2.1.0",
     "jest-environment-jsdom": "^29.0.2",
     "jest-runtime": "^29.0.2",
-    "js-yaml": "^4.1.0",
     "json-schema": "^0.4.0",
     "lodash": "^4.17.21",
     "mini-css-extract-plugin": "^2.4.2",
@@ -106,7 +104,6 @@
     "node-libs-browser": "^2.2.1",
     "npm-packlist": "^5.0.0",
     "ora": "^5.3.0",
-    "p-limit": "^3.0.2",
     "postcss": "^8.1.0",
     "process": "^0.11.10",
     "react-dev-utils": "^12.0.0-next.60",
diff --git a/packages/cli/src/commands/index.ts b/packages/cli/src/commands/index.ts
index 713863b685..ba11a53cfd 100644
--- a/packages/cli/src/commands/index.ts
+++ b/packages/cli/src/commands/index.ts
@@ -80,20 +80,6 @@ export function registerRepoCommand(program: Command) {
       lazy(() => import('./repo/list-deprecations').then(m => m.command)),
     );
 
-  command
-    .command('schema:openapi:verify')
-    .description(
-      'Verify that all OpenAPI schemas are valid and have a matching `schemas/openapi.ts` file.',
-    )
-    .action(lazy(() => import('./openapi/verify').then(m => m.bulkCommand)));
-
-  command
-    .command('schema:openapi:generate')
-    .description(
-      'Generates a Typescript file from an OpenAPI yaml spec. For use with the `@backstage/backend-openapi-utils` ApiRouter type.',
-    )
-    .action(lazy(() => import('./openapi/generate').then(m => m.bulkCommand)));
-
   command
     .command('test')
     .allowUnknownOption(true) // Allows the command to run, but we still need to parse raw args
@@ -193,20 +179,6 @@ export function registerScriptCommand(program: Command) {
     .command('postpack')
     .description('Restores the changes made by the prepack command')
     .action(lazy(() => import('./pack').then(m => m.post)));
-
-  command
-    .command('schema:openapi:verify')
-    .description(
-      'Verifies that an OpenAPI spec is defined in both an `openapi.yaml` file and a `schema/openapi.ts` file.',
-    )
-    .action(lazy(() => import('./openapi/verify').then(m => m.command)));
-
-  command
-    .command('schema:openapi:generate')
-    .description(
-      'Generates a `schema/openapi.ts` file from an OpenAPI spec defined in `openapi.yaml`.',
-    )
-    .action(lazy(() => import('./openapi/generate').then(m => m.command)));
 }
 
 export function registerMigrateCommand(program: Command) {
diff --git a/packages/repo-tools/cli-report.md b/packages/repo-tools/cli-report.md
index 0e1b2d2a4c..857c705006 100644
--- a/packages/repo-tools/cli-report.md
+++ b/packages/repo-tools/cli-report.md
@@ -14,6 +14,8 @@ Options:
 Commands:
   api-reports [options] [paths...]
   type-deps
+  schema:openapi:verify [paths...]
+  schema:openapi:generate [paths...]
   help [command]
 ```
 
@@ -33,6 +35,24 @@ Options:
   -h, --help
 ```
 
+### `backstage-repo-tools schema:openapi:generate`
+
+```
+Usage: backstage-repo-tools schema:openapi:generate [options] [paths...]
+
+Options:
+  -h, --help
+```
+
+### `backstage-repo-tools schema:openapi:verify`
+
+```
+Usage: backstage-repo-tools schema:openapi:verify [options] [paths...]
+
+Options:
+  -h, --help
+```
+
 ### `backstage-repo-tools type-deps`
 
 ```
diff --git a/packages/repo-tools/package.json b/packages/repo-tools/package.json
index 4a53cc9976..d5817ef5af 100644
--- a/packages/repo-tools/package.json
+++ b/packages/repo-tools/package.json
@@ -30,6 +30,7 @@
     "backstage-repo-tools": "bin/backstage-repo-tools"
   },
   "dependencies": {
+    "@apidevtools/swagger-parser": "^10.1.0",
     "@backstage/cli-common": "workspace:^",
     "@backstage/errors": "workspace:^",
     "@manypkg/get-packages": "^1.1.3",
@@ -40,7 +41,10 @@
     "fs-extra": "10.1.0",
     "glob": "^8.0.3",
     "is-glob": "^4.0.3",
+    "js-yaml": "^4.1.0",
+    "lodash": "^4.17.21",
     "minimatch": "^5.1.1",
+    "p-limit": "^3.0.2",
     "ts-node": "^10.0.0"
   },
   "devDependencies": {
diff --git a/packages/repo-tools/src/commands/api-reports/api-reports.ts b/packages/repo-tools/src/commands/api-reports/api-reports.ts
index a917975750..b673689b5a 100644
--- a/packages/repo-tools/src/commands/api-reports/api-reports.ts
+++ b/packages/repo-tools/src/commands/api-reports/api-reports.ts
@@ -15,7 +15,6 @@
  */
 
 import { OptionValues } from 'commander';
-import fs from 'fs-extra';
 import {
   createTemporaryTsConfig,
   categorizePackageDirs,
@@ -23,7 +22,7 @@ import {
   runCliExtraction,
   buildDocs,
 } from './api-extractor';
-import { findPackageDirs, paths as cliPaths } from '../../lib/paths';
+import { getMatchingWorkspacePaths, paths as cliPaths } from '../../lib/paths';
 import { generateTypeDeclarations } from './generateTypeDeclarations';
 
 type Options = {
@@ -49,10 +48,7 @@ export const buildApiReports = async (paths: string[] = [], opts: Options) => {
   const omitMessages = parseArrayOption(opts.omitMessages);
 
   const isAllPackages = !paths?.length;
-  const selectedPaths = isAllPackages
-    ? await getWorkspacePackagePathPatterns()
-    : paths;
-  const selectedPackageDirs = await findPackageDirs(selectedPaths);
+  const selectedPackageDirs = await getMatchingWorkspacePaths(paths);
 
   if (isAllPackages && !isCiBuild && !isDocsBuild) {
     console.log('');
@@ -111,26 +107,6 @@ export const buildApiReports = async (paths: string[] = [], opts: Options) => {
   }
 };
 
-/**
- * Retrieves the list of package names in the "workspaces" field of the `package.json` file in the current workspace root.
- *
- * If the file does not exist, or the "workspaces" field is not present, returns `undefined`.
- *
- * @returns {Promise<string[] | undefined>} The list of package names, or `undefined` if not found.
- */
-async function getWorkspacePackagePathPatterns() {
-  const pkgJson = await fs
-    .readJson(cliPaths.resolveTargetRoot('package.json'))
-    .catch(error => {
-      if (error.code === 'ENOENT') {
-        return undefined;
-      }
-      throw error;
-    });
-  const workspaces = pkgJson?.workspaces?.packages;
-  return workspaces;
-}
-
 /**
  * Splits the input string on comma, and returns an array of the resulting substrings.
  * for `undefined` or an empty string, returns an empty array.
diff --git a/packages/repo-tools/src/commands/index.ts b/packages/repo-tools/src/commands/index.ts
index f283e9c743..7aa7acef0b 100644
--- a/packages/repo-tools/src/commands/index.ts
+++ b/packages/repo-tools/src/commands/index.ts
@@ -52,6 +52,20 @@ export function registerCommands(program: Command) {
     .command('type-deps')
     .description('Find inconsistencies in types of all packages and plugins')
     .action(lazy(() => import('./type-deps/type-deps').then(m => m.default)));
+
+  program
+    .command('schema:openapi:verify [paths...]')
+    .description(
+      'Verify that all OpenAPI schemas are valid and have a matching `schemas/openapi.ts` file.',
+    )
+    .action(lazy(() => import('./openapi/verify').then(m => m.bulkCommand)));
+
+  program
+    .command('schema:openapi:generate [paths...]')
+    .description(
+      'Generates a Typescript file from an OpenAPI yaml spec. For use with the `@backstage/backend-openapi-utils` ApiRouter type.',
+    )
+    .action(lazy(() => import('./openapi/generate').then(m => m.bulkCommand)));
 }
 
 // Wraps an action function so that it always exits and handles errors
diff --git a/packages/cli/src/commands/openapi/generate.ts b/packages/repo-tools/src/commands/openapi/generate.ts
similarity index 64%
rename from packages/cli/src/commands/openapi/generate.ts
rename to packages/repo-tools/src/commands/openapi/generate.ts
index 14a1217b7b..8ce88c1dcc 100644
--- a/packages/cli/src/commands/openapi/generate.ts
+++ b/packages/repo-tools/src/commands/openapi/generate.ts
@@ -15,13 +15,10 @@
  */
 
 import fs from 'fs-extra';
-import { paths } from '../../lib/paths';
 import YAML from 'js-yaml';
 import chalk from 'chalk';
 import { resolve } from 'path';
-import { PackageGraph } from '../../lib/monorepo';
-import pLimit from 'p-limit';
-import { relative as relativePath } from 'path';
+import { runner } from './runner';
 
 async function generate(
   directoryPath: string,
@@ -44,36 +41,9 @@ async function generate(
   );
 }
 
-export async function command() {
-  try {
-    await generate(paths.resolveTarget('.'));
-    console.log(chalk.green('OpenAPI files successfully generated.'));
-  } catch (err) {
-    console.error(chalk.red(err.message));
-    process.exit(1);
-  }
-}
-
-export async function bulkCommand(): Promise<void> {
-  const packages = await PackageGraph.listTargetPackages();
-  const limit = pLimit(5);
-
-  const resultsList = await Promise.all(
-    packages.map(pkg =>
-      limit(async () => {
-        let resultText = '';
-        try {
-          await generate(pkg.dir, { skipMissingYamlFile: true });
-        } catch (err) {
-          resultText = err.message;
-        }
-
-        return {
-          relativeDir: relativePath(paths.targetRoot, pkg.dir),
-          resultText,
-        };
-      }),
-    ),
+export async function bulkCommand(paths: string[] = []): Promise<void> {
+  const resultsList = await runner(paths, (dir: string) =>
+    generate(dir, { skipMissingYamlFile: true }),
   );
 
   let failed = false;
@@ -93,5 +63,7 @@ export async function bulkCommand(): Promise<void> {
 
   if (failed) {
     process.exit(1);
+  } else {
+    console.log(chalk.green('Generated all files.'));
   }
 }
diff --git a/packages/repo-tools/src/commands/openapi/runner.ts b/packages/repo-tools/src/commands/openapi/runner.ts
new file mode 100644
index 0000000000..4b1b0167bf
--- /dev/null
+++ b/packages/repo-tools/src/commands/openapi/runner.ts
@@ -0,0 +1,49 @@
+/*
+ * Copyright 2023 The Backstage Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { getMatchingWorkspacePaths } from '../../lib/paths';
+import pLimit from 'p-limit';
+import { relative as relativePath } from 'path';
+import { paths as cliPaths } from '../../lib/paths';
+
+export async function runner(
+  paths: string[],
+  command: (dir: string) => Promise<void>,
+) {
+  const packages = await getMatchingWorkspacePaths(paths);
+  const limit = pLimit(5);
+
+  const resultsList = await Promise.all(
+    packages.map(pkg =>
+      limit(async () => {
+        let resultText = '';
+        try {
+          console.log(`## Processing ${pkg}`);
+          await command(pkg);
+        } catch (err) {
+          resultText = err.message;
+        }
+
+        return {
+          relativeDir: relativePath(cliPaths.targetRoot, pkg),
+          resultText,
+        };
+      }),
+    ),
+  );
+
+  return resultsList;
+}
diff --git a/packages/cli/src/commands/openapi/verify.ts b/packages/repo-tools/src/commands/openapi/verify.ts
similarity index 51%
rename from packages/cli/src/commands/openapi/verify.ts
rename to packages/repo-tools/src/commands/openapi/verify.ts
index ad0031622f..c45e388a07 100644
--- a/packages/cli/src/commands/openapi/verify.ts
+++ b/packages/repo-tools/src/commands/openapi/verify.ts
@@ -15,41 +15,16 @@
  */
 
 import fs from 'fs-extra';
-import { paths } from '../../lib/paths';
 import YAML from 'js-yaml';
-import { isEqual } from 'lodash';
-import { join, resolve } from 'path';
+import { isEqual, cloneDeep } from 'lodash';
+import { join } from 'path';
 import chalk from 'chalk';
-import { relative as relativePath } from 'path';
-import { PackageGraph } from '../../lib/monorepo';
-import { cloneDeep } from 'lodash';
+import { relative as relativePath, resolve as resolvePath } from 'path';
 import Parser from '@apidevtools/swagger-parser';
-import { detectRoleFromPackage } from '../../lib/role';
-import pLimit from 'p-limit';
-
-const SUPPORTED_ROLES = [
-  'backend',
-  'backend-plugin',
-  'backend-plugin-module',
-  'node-library',
-];
-
-async function verify(
-  directoryPath: string,
-  config: { checkRole: boolean } = { checkRole: false },
-) {
-  const { checkRole } = config ?? {};
-  if (checkRole) {
-    const role = detectRoleFromPackage(
-      await fs.readJson(resolve(directoryPath, 'package.json')),
-    );
-
-    if (!role || !SUPPORTED_ROLES.includes(role)) {
-      console.log(chalk.red(`Unsupported role ${role}`));
-      process.exit(1);
-    }
-  }
+import { runner } from './runner';
+import { paths as cliPaths } from '../../lib/paths';
 
+async function verify(directoryPath: string) {
   const openapiPath = join(directoryPath, 'openapi.yaml');
   if (!(await fs.pathExists(openapiPath))) {
     return;
@@ -62,51 +37,27 @@ async function verify(
   if (!(await fs.pathExists(schemaPath))) {
     throw new Error('No `schema/openapi.ts` file found.');
   }
-  const schema = await import(join(directoryPath, 'schema/openapi'));
+
+  const schema = await import(
+    resolvePath(join(directoryPath, 'schema/openapi'))
+  );
+
   if (!schema.default) {
     throw new Error('`schemas/openapi.ts` needs to have a default export.');
   }
   if (!isEqual(schema.default, yaml)) {
     throw new Error(
       `\`openapi.yaml\` and \`schema/openapi.ts\` do not match. Please run \`yarn --cwd ${relativePath(
-        paths.targetRoot,
+        cliPaths.targetRoot,
         directoryPath,
       )} schema:openapi:generate\` to regenerate \`schema/openapi.ts\`.`,
     );
   }
 }
 
-export async function command() {
-  try {
-    await verify(paths.resolveTarget('.'), { checkRole: true });
-    console.log(chalk.green('OpenAPI files are valid.'));
-  } catch (err) {
-    console.error(chalk.red(err.message));
-    process.exit(1);
-  }
-}
-
-export async function bulkCommand(): Promise<void> {
-  const packages = await PackageGraph.listTargetPackages();
-  const limit = pLimit(5);
-
-  const resultsList = await Promise.all(
-    packages.map(pkg =>
-      limit(async () => {
-        let resultText = '';
-        try {
-          await verify(pkg.dir);
-        } catch (err) {
-          resultText = err.message;
-        }
-
-        return {
-          relativeDir: relativePath(paths.targetRoot, pkg.dir),
-          resultText,
-        };
-      }),
-    ),
-  );
+export async function bulkCommand(paths: string[] = []): Promise<void> {
+  console.log(paths);
+  const resultsList = await runner(paths, dir => verify(dir));
 
   let failed = false;
   for (const { relativeDir, resultText } of resultsList) {
@@ -121,5 +72,7 @@ export async function bulkCommand(): Promise<void> {
 
   if (failed) {
     process.exit(1);
+  } else {
+    console.log(chalk.green('Verified all files.'));
   }
 }
diff --git a/packages/repo-tools/src/lib/paths.ts b/packages/repo-tools/src/lib/paths.ts
index 01a5d92db1..71eff3d941 100644
--- a/packages/repo-tools/src/lib/paths.ts
+++ b/packages/repo-tools/src/lib/paths.ts
@@ -66,3 +66,39 @@ export async function findPackageDirs(selectedPaths: string[] = []) {
   }
   return packageDirs;
 }
+
+/**
+ * Retrieves the list of package names in the "workspaces" field of the `package.json` file in the current workspace root.
+ *
+ * If the file does not exist, or the "workspaces" field is not present, returns `undefined`.
+ *
+ * @returns The list of package names, or `undefined` if not found.
+ */
+export async function getWorkspacePackagePathPatterns(): Promise<
+  string[] | undefined
+> {
+  const pkgJson = await fs
+    .readJson(paths.resolveTargetRoot('package.json'))
+    .catch(error => {
+      if (error.code === 'ENOENT') {
+        return undefined;
+      }
+      throw error;
+    });
+  const workspaces = pkgJson?.workspaces?.packages;
+  return workspaces;
+}
+
+/**
+ * Given a list of paths from the user or none and return the listing package directories from the
+ *  workspace.
+ * @param cliPaths
+ * @returns
+ */
+export async function getMatchingWorkspacePaths(cliPaths: string[]) {
+  const isAllPackages = !cliPaths?.length;
+  const selectedPaths = isAllPackages
+    ? await getWorkspacePackagePathPatterns()
+    : cliPaths;
+  return await findPackageDirs(selectedPaths);
+}
diff --git a/yarn.lock b/yarn.lock
index 3697631867..85cabd15e9 100644
--- a/yarn.lock
+++ b/yarn.lock
@@ -3958,7 +3958,6 @@ __metadata:
   version: 0.0.0-use.local
   resolution: "@backstage/cli@workspace:packages/cli"
   dependencies:
-    "@apidevtools/swagger-parser": ^10.1.0
     "@backstage/backend-common": "workspace:^"
     "@backstage/cli-common": "workspace:^"
     "@backstage/config": "workspace:^"
@@ -4050,7 +4049,6 @@ __metadata:
     jest-css-modules: ^2.1.0
     jest-environment-jsdom: ^29.0.2
     jest-runtime: ^29.0.2
-    js-yaml: ^4.1.0
     json-schema: ^0.4.0
     lodash: ^4.17.21
     mini-css-extract-plugin: ^2.4.2
@@ -4062,7 +4060,6 @@ __metadata:
     nodemon: ^2.0.2
     npm-packlist: ^5.0.0
     ora: ^5.3.0
-    p-limit: ^3.0.2
     postcss: ^8.1.0
     process: ^0.11.10
     react-dev-utils: ^12.0.0-next.60
@@ -9611,6 +9608,7 @@ __metadata:
   version: 0.0.0-use.local
   resolution: "@backstage/repo-tools@workspace:packages/repo-tools"
   dependencies:
+    "@apidevtools/swagger-parser": ^10.1.0
     "@backstage/cli": "workspace:^"
     "@backstage/cli-common": "workspace:^"
     "@backstage/errors": "workspace:^"
@@ -9626,8 +9624,11 @@ __metadata:
     fs-extra: 10.1.0
     glob: ^8.0.3
     is-glob: ^4.0.3
+    js-yaml: ^4.1.0
+    lodash: ^4.17.21
     minimatch: ^5.1.1
     mock-fs: ^5.1.0
+    p-limit: ^3.0.2
     ts-node: ^10.0.0
   peerDependencies:
     "@microsoft/api-extractor-model": "*"

From f14d03d08a40573e2e568a07f66c9b98888096f4 Mon Sep 17 00:00:00 2001
From: Aramis Sennyey <sennyeya@amazon.com>
Date: Fri, 17 Mar 2023 14:21:37 -0400
Subject: [PATCH 54/61] Need to escape oatx.

Signed-off-by: Aramis Sennyey <sennyeya@amazon.com>
---
 plugins/openapi-utils/README.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/plugins/openapi-utils/README.md b/plugins/openapi-utils/README.md
index 04344baa9d..2f624f7620 100644
--- a/plugins/openapi-utils/README.md
+++ b/plugins/openapi-utils/README.md
@@ -2,7 +2,7 @@
 
 ## Summary
 
-This package is meant to provide a typed Express router for an OpenAPI spec. Based on the [oatx](https://github.com/varanauskas/oatx) library and adapted to override Express values.
+This package is meant to provide a typed Express router for an OpenAPI spec. Based on the [`oatx`](https://github.com/varanauskas/oatx) library and adapted to override Express values.
 
 ## Getting Started
 

From 1f5800ae6d7cfaf873e71adf145d3f1bfc882e6d Mon Sep 17 00:00:00 2001
From: Aramis Sennyey <sennyeya@amazon.com>
Date: Mon, 20 Mar 2023 10:31:46 -0400
Subject: [PATCH 55/61] Rename to package/backend-openapi-utils.

Signed-off-by: Aramis Sennyey <sennyeya@amazon.com>
---
 .../backend-openapi-utils}/.eslintrc.js                       | 0
 .../backend-openapi-utils}/README.md                          | 0
 .../backend-openapi-utils}/api-report.md                      | 0
 .../backend-openapi-utils}/package.json                       | 0
 .../backend-openapi-utils}/src/index.ts                       | 0
 .../backend-openapi-utils}/src/router.ts                      | 0
 .../backend-openapi-utils}/src/setupTests.ts                  | 0
 .../backend-openapi-utils}/src/types/common.ts                | 0
 .../backend-openapi-utils}/src/types/express.ts               | 0
 .../backend-openapi-utils}/src/types/immutable.ts             | 0
 .../backend-openapi-utils}/src/types/index.ts                 | 0
 .../backend-openapi-utils}/src/types/params.ts                | 0
 .../backend-openapi-utils}/src/types/requests.ts              | 0
 .../backend-openapi-utils}/src/types/responses.ts             | 0
 yarn.lock                                                     | 4 ++--
 15 files changed, 2 insertions(+), 2 deletions(-)
 rename {plugins/openapi-utils => packages/backend-openapi-utils}/.eslintrc.js (100%)
 rename {plugins/openapi-utils => packages/backend-openapi-utils}/README.md (100%)
 rename {plugins/openapi-utils => packages/backend-openapi-utils}/api-report.md (100%)
 rename {plugins/openapi-utils => packages/backend-openapi-utils}/package.json (100%)
 rename {plugins/openapi-utils => packages/backend-openapi-utils}/src/index.ts (100%)
 rename {plugins/openapi-utils => packages/backend-openapi-utils}/src/router.ts (100%)
 rename {plugins/openapi-utils => packages/backend-openapi-utils}/src/setupTests.ts (100%)
 rename {plugins/openapi-utils => packages/backend-openapi-utils}/src/types/common.ts (100%)
 rename {plugins/openapi-utils => packages/backend-openapi-utils}/src/types/express.ts (100%)
 rename {plugins/openapi-utils => packages/backend-openapi-utils}/src/types/immutable.ts (100%)
 rename {plugins/openapi-utils => packages/backend-openapi-utils}/src/types/index.ts (100%)
 rename {plugins/openapi-utils => packages/backend-openapi-utils}/src/types/params.ts (100%)
 rename {plugins/openapi-utils => packages/backend-openapi-utils}/src/types/requests.ts (100%)
 rename {plugins/openapi-utils => packages/backend-openapi-utils}/src/types/responses.ts (100%)

diff --git a/plugins/openapi-utils/.eslintrc.js b/packages/backend-openapi-utils/.eslintrc.js
similarity index 100%
rename from plugins/openapi-utils/.eslintrc.js
rename to packages/backend-openapi-utils/.eslintrc.js
diff --git a/plugins/openapi-utils/README.md b/packages/backend-openapi-utils/README.md
similarity index 100%
rename from plugins/openapi-utils/README.md
rename to packages/backend-openapi-utils/README.md
diff --git a/plugins/openapi-utils/api-report.md b/packages/backend-openapi-utils/api-report.md
similarity index 100%
rename from plugins/openapi-utils/api-report.md
rename to packages/backend-openapi-utils/api-report.md
diff --git a/plugins/openapi-utils/package.json b/packages/backend-openapi-utils/package.json
similarity index 100%
rename from plugins/openapi-utils/package.json
rename to packages/backend-openapi-utils/package.json
diff --git a/plugins/openapi-utils/src/index.ts b/packages/backend-openapi-utils/src/index.ts
similarity index 100%
rename from plugins/openapi-utils/src/index.ts
rename to packages/backend-openapi-utils/src/index.ts
diff --git a/plugins/openapi-utils/src/router.ts b/packages/backend-openapi-utils/src/router.ts
similarity index 100%
rename from plugins/openapi-utils/src/router.ts
rename to packages/backend-openapi-utils/src/router.ts
diff --git a/plugins/openapi-utils/src/setupTests.ts b/packages/backend-openapi-utils/src/setupTests.ts
similarity index 100%
rename from plugins/openapi-utils/src/setupTests.ts
rename to packages/backend-openapi-utils/src/setupTests.ts
diff --git a/plugins/openapi-utils/src/types/common.ts b/packages/backend-openapi-utils/src/types/common.ts
similarity index 100%
rename from plugins/openapi-utils/src/types/common.ts
rename to packages/backend-openapi-utils/src/types/common.ts
diff --git a/plugins/openapi-utils/src/types/express.ts b/packages/backend-openapi-utils/src/types/express.ts
similarity index 100%
rename from plugins/openapi-utils/src/types/express.ts
rename to packages/backend-openapi-utils/src/types/express.ts
diff --git a/plugins/openapi-utils/src/types/immutable.ts b/packages/backend-openapi-utils/src/types/immutable.ts
similarity index 100%
rename from plugins/openapi-utils/src/types/immutable.ts
rename to packages/backend-openapi-utils/src/types/immutable.ts
diff --git a/plugins/openapi-utils/src/types/index.ts b/packages/backend-openapi-utils/src/types/index.ts
similarity index 100%
rename from plugins/openapi-utils/src/types/index.ts
rename to packages/backend-openapi-utils/src/types/index.ts
diff --git a/plugins/openapi-utils/src/types/params.ts b/packages/backend-openapi-utils/src/types/params.ts
similarity index 100%
rename from plugins/openapi-utils/src/types/params.ts
rename to packages/backend-openapi-utils/src/types/params.ts
diff --git a/plugins/openapi-utils/src/types/requests.ts b/packages/backend-openapi-utils/src/types/requests.ts
similarity index 100%
rename from plugins/openapi-utils/src/types/requests.ts
rename to packages/backend-openapi-utils/src/types/requests.ts
diff --git a/plugins/openapi-utils/src/types/responses.ts b/packages/backend-openapi-utils/src/types/responses.ts
similarity index 100%
rename from plugins/openapi-utils/src/types/responses.ts
rename to packages/backend-openapi-utils/src/types/responses.ts
diff --git a/yarn.lock b/yarn.lock
index 85cabd15e9..6eb6bd0bdf 100644
--- a/yarn.lock
+++ b/yarn.lock
@@ -3827,9 +3827,9 @@ __metadata:
   languageName: unknown
   linkType: soft
 
-"@backstage/backend-openapi-utils@workspace:^, @backstage/backend-openapi-utils@workspace:plugins/openapi-utils":
+"@backstage/backend-openapi-utils@workspace:^, @backstage/backend-openapi-utils@workspace:packages/backend-openapi-utils":
   version: 0.0.0-use.local
-  resolution: "@backstage/backend-openapi-utils@workspace:plugins/openapi-utils"
+  resolution: "@backstage/backend-openapi-utils@workspace:packages/backend-openapi-utils"
   dependencies:
     "@backstage/cli": "workspace:^"
     "@types/express": ^4.17.6

From ef770923df4f39c0a0dce4ef57013dfe98bd3d95 Mon Sep 17 00:00:00 2001
From: Aramis Sennyey <sennyeya@amazon.com>
Date: Mon, 3 Apr 2023 12:22:50 -0400
Subject: [PATCH 56/61] Lint on generate success. Move YAML file to src/schema/

Signed-off-by: Aramis Sennyey <sennyeya@amazon.com>
---
 .changeset/cold-seahorses-greet.md             |  2 +-
 .changeset/fresh-lions-compete.md              |  2 +-
 .github/workflows/ci.yml                       |  2 +-
 packages/backend-openapi-utils/README.md       |  4 ++--
 .../src/commands/openapi/constants.ts          | 18 ++++++++++++++++++
 .../src/commands/openapi/generate.ts           | 16 ++++++++++++----
 .../repo-tools/src/commands/openapi/verify.ts  | 18 ++++++++----------
 packages/repo-tools/src/lib/paths.ts           |  8 ++++----
 .../{ => src}/schema/openapi.ts                |  0
 .../{ => src/schema}/openapi.yaml              |  0
 .../src/service/createRouter.ts                |  2 +-
 11 files changed, 48 insertions(+), 24 deletions(-)
 create mode 100644 packages/repo-tools/src/commands/openapi/constants.ts
 rename plugins/catalog-backend/{ => src}/schema/openapi.ts (100%)
 rename plugins/catalog-backend/{ => src/schema}/openapi.yaml (100%)

diff --git a/.changeset/cold-seahorses-greet.md b/.changeset/cold-seahorses-greet.md
index e50cdfd673..71bc5db2cc 100644
--- a/.changeset/cold-seahorses-greet.md
+++ b/.changeset/cold-seahorses-greet.md
@@ -2,4 +2,4 @@
 '@backstage/plugin-catalog-backend': patch
 ---
 
-Update `openapi.yaml` and use `ApiRouter` type from `@backstage/backend-openapi-utils` to handle automatic types from the OpenAPI spec file.
+Updates and moves OpenAPI spec to `src/schema/openapi.yaml` and uses `ApiRouter` type from `@backstage/backend-openapi-utils` to handle automatic types from the OpenAPI spec file.
diff --git a/.changeset/fresh-lions-compete.md b/.changeset/fresh-lions-compete.md
index 76c2161c37..87f15f538d 100644
--- a/.changeset/fresh-lions-compete.md
+++ b/.changeset/fresh-lions-compete.md
@@ -2,4 +2,4 @@
 '@backstage/repo-tools': minor
 ---
 
-Adding two new commands to support OpenAPI spec writing, `schema:openapi:generate` to generate the Typescript file that `@backstage/backend-openapi-utils` needs for typing and `schema:openapi:verify` to verify that this file exists and matches your `openapi.yaml` file.
+Adding two new commands to support OpenAPI spec writing, `schema:openapi:generate` to generate the Typescript file that `@backstage/backend-openapi-utils` needs for typing and `schema:openapi:verify` to verify that this file exists and matches your `src/schema/openapi.yaml` file.
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 3788687ab2..fb03709cce 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -92,7 +92,7 @@ jobs:
       - name: verify api reference
         run: node scripts/verify-api-reference.js
 
-      - name: verify openapi.yaml matches schema/openapi.ts files
+      - name: verify openapi yaml file matches generated ts file
         run: yarn backstage-repo-tools schema:openapi:verify
 
       - name: verify doc links
diff --git a/packages/backend-openapi-utils/README.md b/packages/backend-openapi-utils/README.md
index 2f624f7620..51455ccccb 100644
--- a/packages/backend-openapi-utils/README.md
+++ b/packages/backend-openapi-utils/README.md
@@ -8,13 +8,13 @@ This package is meant to provide a typed Express router for an OpenAPI spec. Bas
 
 ### Configuration
 
-1. Run `yarn --cwd <package-dir> backstage-cli package schema:openapi:generate` to translate your `openapi.yaml` to a new Typescript file in `schema/openapi.ts`. In the case of projects that require linting + a license header, you will need to do this manually.
+1. Run `yarn --cwd <package-dir> backstage-cli package schema:openapi:generate` to translate your `src/schema/openapi.yaml` to a new Typescript file in `src/schema/openapi.ts`. In the case of projects that require linting + a license header, you will need to do this manually.
 
 2. In your plugin's `src/service/createRouter.ts`,
 
 ```ts
 import {ApiRouter} from `@backstage/backend-openapi-utils`;
-import spec from '../../schema/openapi'
+import spec from '../schema/openapi'
 ...
 
 export function createRouter(){
diff --git a/packages/repo-tools/src/commands/openapi/constants.ts b/packages/repo-tools/src/commands/openapi/constants.ts
new file mode 100644
index 0000000000..7c91f423c1
--- /dev/null
+++ b/packages/repo-tools/src/commands/openapi/constants.ts
@@ -0,0 +1,18 @@
+/*
+ * Copyright 2023 The Backstage Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+export const YAML_SCHEMA_PATH = 'src/schema/openapi.yaml';
+export const TS_MODULE = 'src/schema/openapi';
+export const TS_SCHEMA_PATH = `${TS_MODULE}.ts`;
diff --git a/packages/repo-tools/src/commands/openapi/generate.ts b/packages/repo-tools/src/commands/openapi/generate.ts
index 8ce88c1dcc..fc73013765 100644
--- a/packages/repo-tools/src/commands/openapi/generate.ts
+++ b/packages/repo-tools/src/commands/openapi/generate.ts
@@ -19,26 +19,34 @@ import YAML from 'js-yaml';
 import chalk from 'chalk';
 import { resolve } from 'path';
 import { runner } from './runner';
+import { TS_SCHEMA_PATH, YAML_SCHEMA_PATH } from './constants';
+import { promisify } from 'util';
+import { exec as execCb } from 'child_process';
+
+const exec = promisify(execCb);
 
 async function generate(
   directoryPath: string,
   config?: { skipMissingYamlFile: boolean },
 ) {
   const { skipMissingYamlFile } = config ?? {};
-  const openapiPath = resolve(directoryPath, 'openapi.yaml');
+  const openapiPath = resolve(directoryPath, YAML_SCHEMA_PATH);
   if (!(await fs.pathExists(openapiPath))) {
     if (skipMissingYamlFile) {
       return;
     }
-    throw new Error('Could not find openapi.yaml in root of directory.');
+    throw new Error(`Could not find ${YAML_SCHEMA_PATH} in root of directory.`);
   }
   const yaml = YAML.load(await fs.readFile(openapiPath, 'utf8'));
 
-  // For now, we're not adding a header or linting after pasting.
+  const tsPath = resolve(directoryPath, TS_SCHEMA_PATH);
+
   await fs.writeFile(
-    resolve(directoryPath, 'schema/openapi.ts'),
+    tsPath,
     `export default ${JSON.stringify(yaml, null, 2)} as const`,
   );
+
+  await exec(`yarn backstage-cli package lint --fix ${tsPath}`);
 }
 
 export async function bulkCommand(paths: string[] = []): Promise<void> {
diff --git a/packages/repo-tools/src/commands/openapi/verify.ts b/packages/repo-tools/src/commands/openapi/verify.ts
index c45e388a07..8febe11cf5 100644
--- a/packages/repo-tools/src/commands/openapi/verify.ts
+++ b/packages/repo-tools/src/commands/openapi/verify.ts
@@ -23,9 +23,10 @@ import { relative as relativePath, resolve as resolvePath } from 'path';
 import Parser from '@apidevtools/swagger-parser';
 import { runner } from './runner';
 import { paths as cliPaths } from '../../lib/paths';
+import { TS_MODULE, TS_SCHEMA_PATH, YAML_SCHEMA_PATH } from './constants';
 
 async function verify(directoryPath: string) {
-  const openapiPath = join(directoryPath, 'openapi.yaml');
+  const openapiPath = join(directoryPath, YAML_SCHEMA_PATH);
   if (!(await fs.pathExists(openapiPath))) {
     return;
   }
@@ -33,30 +34,27 @@ async function verify(directoryPath: string) {
   const yaml = YAML.load(await fs.readFile(openapiPath, 'utf8'));
   await Parser.validate(cloneDeep(yaml) as any);
 
-  const schemaPath = join(directoryPath, 'schema/openapi.ts');
+  const schemaPath = join(directoryPath, TS_SCHEMA_PATH);
   if (!(await fs.pathExists(schemaPath))) {
-    throw new Error('No `schema/openapi.ts` file found.');
+    throw new Error(`No \`${TS_SCHEMA_PATH}\` file found.`);
   }
 
-  const schema = await import(
-    resolvePath(join(directoryPath, 'schema/openapi'))
-  );
+  const schema = await import(resolvePath(join(directoryPath, TS_MODULE)));
 
   if (!schema.default) {
-    throw new Error('`schemas/openapi.ts` needs to have a default export.');
+    throw new Error(`\`${TS_SCHEMA_PATH}\` needs to have a default export.`);
   }
   if (!isEqual(schema.default, yaml)) {
     throw new Error(
-      `\`openapi.yaml\` and \`schema/openapi.ts\` do not match. Please run \`yarn --cwd ${relativePath(
+      `\`${YAML_SCHEMA_PATH}\` and \`${TS_SCHEMA_PATH}\` do not match. Please run \`yarn --cwd ${relativePath(
         cliPaths.targetRoot,
         directoryPath,
-      )} schema:openapi:generate\` to regenerate \`schema/openapi.ts\`.`,
+      )} schema:openapi:generate\` to regenerate \`${TS_SCHEMA_PATH}\`.`,
     );
   }
 }
 
 export async function bulkCommand(paths: string[] = []): Promise<void> {
-  console.log(paths);
   const resultsList = await runner(paths, dir => verify(dir));
 
   let failed = false;
diff --git a/packages/repo-tools/src/lib/paths.ts b/packages/repo-tools/src/lib/paths.ts
index 71eff3d941..73feeae21c 100644
--- a/packages/repo-tools/src/lib/paths.ts
+++ b/packages/repo-tools/src/lib/paths.ts
@@ -90,10 +90,10 @@ export async function getWorkspacePackagePathPatterns(): Promise<
 }
 
 /**
- * Given a list of paths from the user or none and return the listing package directories from the
- *  workspace.
- * @param cliPaths
- * @returns
+ * Given a list of paths from the user, returns the listing package directories from the
+ *  workspace. Returns all directories if no paths are given.
+ * @param cliPaths User given paths from CLI.
+ * @returns Matching package directories or all if no cli paths passed in.
  */
 export async function getMatchingWorkspacePaths(cliPaths: string[]) {
   const isAllPackages = !cliPaths?.length;
diff --git a/plugins/catalog-backend/schema/openapi.ts b/plugins/catalog-backend/src/schema/openapi.ts
similarity index 100%
rename from plugins/catalog-backend/schema/openapi.ts
rename to plugins/catalog-backend/src/schema/openapi.ts
diff --git a/plugins/catalog-backend/openapi.yaml b/plugins/catalog-backend/src/schema/openapi.yaml
similarity index 100%
rename from plugins/catalog-backend/openapi.yaml
rename to plugins/catalog-backend/src/schema/openapi.yaml
diff --git a/plugins/catalog-backend/src/service/createRouter.ts b/plugins/catalog-backend/src/service/createRouter.ts
index 3aff802660..830e909272 100644
--- a/plugins/catalog-backend/src/service/createRouter.ts
+++ b/plugins/catalog-backend/src/service/createRouter.ts
@@ -51,7 +51,7 @@ import {
   validateRequestBody,
 } from './util';
 import type { ApiRouter } from '@backstage/backend-openapi-utils';
-import spec from '../../schema/openapi';
+import spec from '../schema/openapi';
 
 /**
  * Options used by {@link createRouter}.

From 29a44b8982da505a7aa1a5ed9c4fa4756cfe629f Mon Sep 17 00:00:00 2001
From: Aramis Sennyey <sennyeya@amazon.com>
Date: Mon, 3 Apr 2023 13:31:08 -0400
Subject: [PATCH 57/61] Add export for core as a whole type.

Signed-off-by: Aramis Sennyey <sennyeya@amazon.com>
---
 packages/backend-openapi-utils/api-report.md  | 634 +++++++++++++++++-
 packages/backend-openapi-utils/src/index.ts   |   3 +-
 packages/backend-openapi-utils/src/router.ts  |  20 +-
 .../backend-openapi-utils/src/types/common.ts |  77 +++
 .../src/types/express.ts                      |   7 +-
 .../src/types/immutable.ts                    |  59 +-
 .../backend-openapi-utils/src/types/index.ts  |  35 +-
 .../backend-openapi-utils/src/types/params.ts |  42 +-
 .../src/types/requests.ts                     |  11 +-
 .../src/types/responses.ts                    |  42 +-
 10 files changed, 837 insertions(+), 93 deletions(-)

diff --git a/packages/backend-openapi-utils/api-report.md b/packages/backend-openapi-utils/api-report.md
index 7e5024b15b..af102d4df8 100644
--- a/packages/backend-openapi-utils/api-report.md
+++ b/packages/backend-openapi-utils/api-report.md
@@ -3,28 +3,642 @@
 > Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.com/).
 
 ```ts
+import type { ContentObject } from 'openapi3-ts';
+import { default as core_2 } from 'express-serve-static-core';
+import { FromSchema } from 'json-schema-to-ts';
+import { JSONSchema7 } from 'json-schema-to-ts';
+import type { OpenAPIObject } from 'openapi3-ts';
+import type { ParameterObject } from 'openapi3-ts';
+import type { ReferenceObject } from 'openapi3-ts';
+import type { RequestBodyObject } from 'openapi3-ts';
+import type { ResponseObject } from 'openapi3-ts';
 import { Router } from 'express';
+import type { SchemaObject } from 'openapi3-ts';
 
 // @public
-export interface ApiRouter<Doc extends core.Spec> extends Router {
+export interface ApiRouter<Doc extends RequiredDoc> extends Router {
   // (undocumented)
-  all: core.RequestMatcher<Doc, this, 'all'>;
+  all: DocRequestMatcher<Doc, this, 'all'>;
   // (undocumented)
-  delete: core.RequestMatcher<Doc, this, 'delete'>;
+  delete: DocRequestMatcher<Doc, this, 'delete'>;
   // (undocumented)
-  get: core.RequestMatcher<Doc, this, 'get'>;
+  get: DocRequestMatcher<Doc, this, 'get'>;
   // (undocumented)
-  head: core.RequestMatcher<Doc, this, 'head'>;
+  head: DocRequestMatcher<Doc, this, 'head'>;
   // (undocumented)
-  options: core.RequestMatcher<Doc, this, 'options'>;
+  options: DocRequestMatcher<Doc, this, 'options'>;
   // (undocumented)
-  patch: core.RequestMatcher<Doc, this, 'patch'>;
+  patch: DocRequestMatcher<Doc, this, 'patch'>;
   // (undocumented)
-  post: core.RequestMatcher<Doc, this, 'post'>;
+  post: DocRequestMatcher<Doc, this, 'post'>;
   // (undocumented)
-  put: core.RequestMatcher<Doc, this, 'put'>;
+  put: DocRequestMatcher<Doc, this, 'put'>;
 }
 
 // @public (undocumented)
-export namespace core {}
+type ComponentRef<
+  Doc extends RequiredDoc,
+  Type extends ComponentTypes<Doc>,
+  Ref extends ImmutableReferenceObject,
+> = Ref extends {
+  $ref: `#/components/${Type}/${infer Name}`;
+}
+  ? Name extends keyof Doc['components'][Type]
+    ? Doc['components'][Type][Name] extends ImmutableReferenceObject
+      ? ComponentRef<Doc, Type, Doc['components'][Type][Name]>
+      : Doc['components'][Type][Name]
+    : never
+  : never;
+
+// @public (undocumented)
+type ComponentTypes<Doc extends RequiredDoc> = Extract<
+  keyof Doc['components'],
+  string
+>;
+
+// @public (undocumented)
+type ConvertAll<T, R extends ReadonlyArray<unknown> = []> = T extends [
+  infer First extends JSONSchema7,
+  ...infer Rest,
+]
+  ? ConvertAll<Rest, [...R, FromSchema<First>]>
+  : R;
+
+// @public (undocumented)
+interface CookieObject extends ParameterObject {
+  // (undocumented)
+  in: 'cookie';
+  // (undocumented)
+  style?: 'form';
+}
+
+// @public (undocumented)
+type CookieSchema<
+  Doc extends RequiredDoc,
+  Path extends PathTemplate<Extract<keyof Doc['paths'], string>>,
+  Method extends DocPathMethod<Doc, Path>,
+> = ParametersSchema<Doc, DocPath<Doc, Path>, Method, ImmutableCookieObject>;
+
+declare namespace core {
+  export {
+    RequiredDoc,
+    PathDoc,
+    ValueOf,
+    PathTemplate,
+    DocPath,
+    DocPathTemplate,
+    DocPathMethod,
+    MethodAwareDocPath,
+    DocOperation,
+    ComponentTypes,
+    ComponentRef,
+    SchemaRef,
+    ObjectWithContentSchema,
+    UnionToIntersection,
+    LastOf,
+    Push,
+    TuplifyUnion,
+    ConvertAll,
+    UnknownIfNever,
+    ToTypeSafe,
+    DiscriminateUnion,
+    MapDiscriminatedUnion,
+    PickOptionalKeys,
+    PickRequiredKeys,
+    OptionalMap,
+    RequiredMap,
+    FullMap,
+    Filter,
+    DocRequestHandler,
+    DocRequestHandlerParams,
+    DocRequestMatcher,
+    Immutable,
+    ImmutableObject,
+    ImmutableReferenceObject,
+    ImmutableOpenAPIObject,
+    ImmutableContentObject,
+    ImmutableRequestBodyObject,
+    ImmutableResponseObject,
+    ImmutableParameterObject,
+    HeaderObject,
+    ImmutableHeaderObject,
+    CookieObject,
+    ImmutableCookieObject,
+    QueryObject,
+    ImmutableQueryObject,
+    PathObject,
+    ImmutablePathObject,
+    ImmutableSchemaObject,
+    DocParameter,
+    DocParameters,
+    ResolveDocParameterSchema,
+    ParameterSchema,
+    MapToSchema,
+    ParametersSchema,
+    HeaderSchema,
+    CookieSchema,
+    PathSchema,
+    QuerySchema,
+    RequestBody,
+    RequestBodySchema,
+    RequestBodyToJsonSchema,
+    Response_2 as Response,
+    ResponseSchemas,
+    ResponseBodyToJsonSchema,
+  };
+}
+export { core };
+
+// @public (undocumented)
+type DiscriminateUnion<T, K extends keyof T, V extends T[K]> = Extract<
+  T,
+  Record<K, V>
+>;
+
+// @public (undocumented)
+type DocOperation<
+  Doc extends RequiredDoc,
+  Path extends keyof Doc['paths'],
+  Method extends keyof Doc['paths'][Path],
+> = Doc['paths'][Path][Method];
+
+// @public (undocumented)
+type DocParameter<
+  Doc extends RequiredDoc,
+  Path extends Extract<keyof Doc['paths'], string>,
+  Method extends keyof Doc['paths'][Path],
+  Parameter extends keyof Doc['paths'][Path][Method]['parameters'],
+> = DocOperation<
+  Doc,
+  Path,
+  Method
+>['parameters'][Parameter] extends ImmutableReferenceObject
+  ? 'parameters' extends ComponentTypes<Doc>
+    ? ComponentRef<
+        Doc,
+        'parameters',
+        DocOperation<Doc, Path, Method>['parameters'][Parameter]
+      >
+    : never
+  : DocOperation<Doc, Path, Method>['parameters'][Parameter];
+
+// @public (undocumented)
+type DocParameters<
+  Doc extends RequiredDoc,
+  Path extends Extract<keyof Doc['paths'], string>,
+  Method extends keyof Doc['paths'][Path],
+> = DocOperation<Doc, Path, Method>['parameters'] extends ReadonlyArray<any>
+  ? {
+      [Index in keyof DocOperation<
+        Doc,
+        Path,
+        Method
+      >['parameters']]: DocParameter<Doc, Path, Method, Index>;
+    }
+  : never;
+
+// @public
+type DocPath<
+  Doc extends PathDoc,
+  Path extends PathTemplate<Extract<keyof Doc['paths'], string>>,
+> = ValueOf<{
+  [Template in Extract<
+    keyof Doc['paths'],
+    string
+  >]: Path extends PathTemplate<Template> ? Template : never;
+}>;
+
+// @public (undocumented)
+type DocPathMethod<
+  Doc extends Pick<RequiredDoc, 'paths'>,
+  Path extends DocPathTemplate<Doc>,
+> = keyof Doc['paths'][DocPath<Doc, Path>];
+
+// @public (undocumented)
+type DocPathTemplate<Doc extends PathDoc> = PathTemplate<
+  Extract<keyof Doc['paths'], string>
+>;
+
+// @public
+type DocRequestHandler<
+  Doc extends RequiredDoc,
+  Path extends DocPathTemplate<Doc>,
+  Method extends keyof Doc['paths'][Path],
+> = core_2.RequestHandler<
+  PathSchema<Doc, Path, Method>,
+  ResponseBodyToJsonSchema<Doc, Path, Method>,
+  RequestBodyToJsonSchema<Doc, Path, Method>,
+  QuerySchema<Doc, Path, Method>,
+  Record<string, string>
+>;
+
+// @public
+type DocRequestHandlerParams<
+  Doc extends RequiredDoc,
+  Path extends DocPathTemplate<Doc>,
+  Method extends keyof Doc['paths'][Path],
+> = core_2.RequestHandlerParams<
+  PathSchema<Doc, Path, Method>,
+  ResponseBodyToJsonSchema<Doc, Path, Method>,
+  RequestBodyToJsonSchema<Doc, Path, Method>,
+  QuerySchema<Doc, Path, Method>,
+  Record<string, string>
+>;
+
+// @public
+interface DocRequestMatcher<
+  Doc extends RequiredDoc,
+  T,
+  Method extends
+    | 'all'
+    | 'get'
+    | 'post'
+    | 'put'
+    | 'delete'
+    | 'patch'
+    | 'options'
+    | 'head',
+> {
+  // (undocumented)
+  <Path extends MethodAwareDocPath<Doc, DocPathTemplate<Doc>, Method>>(
+    path: Path,
+    ...handlers: Array<DocRequestHandler<Doc, Path, Method>>
+  ): T;
+  // (undocumented)
+  <Path extends MethodAwareDocPath<Doc, DocPathTemplate<Doc>, Method>>(
+    path: Path,
+    ...handlers: Array<DocRequestHandlerParams<Doc, Path, Method>>
+  ): T;
+}
+
+// @public (undocumented)
+type Filter<T, U> = T extends U ? T : never;
+
+// @public (undocumented)
+type FullMap<
+  T extends {
+    [key: string]: any;
+  },
+> = RequiredMap<T> & OptionalMap<T>;
+
+// @public (undocumented)
+interface HeaderObject extends ParameterObject {
+  // (undocumented)
+  in: 'header';
+  // (undocumented)
+  style: 'simple';
+}
+
+// @public (undocumented)
+type HeaderSchema<
+  Doc extends RequiredDoc,
+  Path extends PathTemplate<Extract<keyof Doc['paths'], string>>,
+  Method extends DocPathMethod<Doc, Path>,
+> = ParametersSchema<Doc, DocPath<Doc, Path>, Method, ImmutableHeaderObject>;
+
+// @public
+type Immutable<T> = T extends
+  | Function
+  | boolean
+  | number
+  | string
+  | null
+  | undefined
+  ? T
+  : T extends Map<infer K, infer V>
+  ? ReadonlyMap<Immutable<K>, Immutable<V>>
+  : T extends Set<infer S>
+  ? ReadonlySet<Immutable<S>>
+  : {
+      readonly [P in keyof T]: Immutable<T[P]>;
+    };
+
+// @public (undocumented)
+type ImmutableContentObject = ImmutableObject<ContentObject>;
+
+// @public (undocumented)
+type ImmutableCookieObject = ImmutableObject<CookieObject>;
+
+// @public (undocumented)
+type ImmutableHeaderObject = ImmutableObject<HeaderObject>;
+
+// @public (undocumented)
+type ImmutableObject<T> = {
+  readonly [K in keyof T]: Immutable<T[K]>;
+};
+
+// @public (undocumented)
+type ImmutableOpenAPIObject = ImmutableObject<OpenAPIObject>;
+
+// @public (undocumented)
+type ImmutableParameterObject = ImmutableObject<ParameterObject>;
+
+// @public (undocumented)
+type ImmutablePathObject = ImmutableObject<PathObject>;
+
+// @public (undocumented)
+type ImmutableQueryObject = ImmutableObject<QueryObject>;
+
+// @public (undocumented)
+type ImmutableReferenceObject = ImmutableObject<ReferenceObject>;
+
+// @public (undocumented)
+type ImmutableRequestBodyObject = ImmutableObject<RequestBodyObject>;
+
+// @public (undocumented)
+type ImmutableResponseObject = ImmutableObject<ResponseObject>;
+
+// @public (undocumented)
+type ImmutableSchemaObject = ImmutableObject<SchemaObject>;
+
+// @public (undocumented)
+type LastOf<T> = UnionToIntersection<
+  T extends any ? () => T : never
+> extends () => infer R
+  ? R
+  : never;
+
+// @public (undocumented)
+type MapDiscriminatedUnion<T extends Record<K, string>, K extends keyof T> = {
+  [V in T[K]]: DiscriminateUnion<T, K, V>;
+};
+
+// @public (undocumented)
+type MapToSchema<
+  Doc extends RequiredDoc,
+  T extends Record<string, ImmutableParameterObject>,
+> = {
+  [V in keyof T]: NonNullable<T[V]> extends ImmutableParameterObject
+    ? ParameterSchema<Doc, NonNullable<T[V]>['schema']>
+    : never;
+};
+
+// @public (undocumented)
+type MethodAwareDocPath<
+  Doc extends PathDoc,
+  Path extends PathTemplate<Extract<keyof Doc['paths'], string>>,
+  Method extends keyof Doc['paths'][Path],
+> = ValueOf<{
+  [Template in Extract<
+    keyof Doc['paths'],
+    string
+  >]: Path extends PathTemplate<Template>
+    ? Method extends DocPathMethod<Doc, Path>
+      ? PathTemplate<Template>
+      : never
+    : never;
+}>;
+
+// @public (undocumented)
+type ObjectWithContentSchema<
+  Doc extends RequiredDoc,
+  Object extends {
+    content?: ImmutableContentObject;
+  },
+> = Object['content'] extends ImmutableContentObject
+  ? SchemaRef<Doc, Object['content']['application/json']['schema']>
+  : never;
+
+// @public (undocumented)
+type OptionalMap<
+  T extends {
+    [key: string]: any;
+  },
+> = {
+  [P in Exclude<PickOptionalKeys<T>, undefined>]?: NonNullable<T[P]>;
+};
+
+// @public (undocumented)
+type ParameterSchema<
+  Doc extends RequiredDoc,
+  Schema extends ImmutableParameterObject['schema'],
+> = ResolveDocParameterSchema<Doc, Schema> extends infer R
+  ? R extends ImmutableSchemaObject
+    ? R extends JSONSchema7
+      ? FromSchema<R>
+      : never
+    : never
+  : never;
+
+// @public (undocumented)
+type ParametersSchema<
+  Doc extends RequiredDoc,
+  Path extends Extract<keyof Doc['paths'], string>,
+  Method extends keyof Doc['paths'][Path],
+  FilterType extends ImmutableParameterObject,
+> = number extends keyof DocParameters<Doc, Path, Method>
+  ? MapToSchema<
+      Doc,
+      FullMap<
+        MapDiscriminatedUnion<
+          Filter<DocParameters<Doc, Path, Method>[number], FilterType>,
+          'name'
+        >
+      >
+    >
+  : never;
+
+// @public (undocumented)
+type PathDoc = Pick<ImmutableOpenAPIObject, 'paths'>;
+
+// @public (undocumented)
+interface PathObject extends ParameterObject {
+  // (undocumented)
+  in: 'path';
+  // (undocumented)
+  style?: 'simple' | 'label' | 'matrix';
+}
+
+// @public (undocumented)
+type PathSchema<
+  Doc extends RequiredDoc,
+  Path extends PathTemplate<Extract<keyof Doc['paths'], string>>,
+  Method extends DocPathMethod<Doc, Path>,
+> = ParametersSchema<Doc, DocPath<Doc, Path>, Method, ImmutablePathObject>;
+
+// @public
+type PathTemplate<Path extends string> =
+  Path extends `${infer Prefix}{${infer PathName}}${infer Suffix}`
+    ? `${Prefix}:${PathName}${PathTemplate<Suffix>}`
+    : Path;
+
+// @public (undocumented)
+type PickOptionalKeys<
+  T extends {
+    [key: string]: any;
+  },
+> = {
+  [K in keyof T]: true extends T[K]['required'] ? never : K;
+}[keyof T];
+
+// @public (undocumented)
+type PickRequiredKeys<
+  T extends {
+    [key: string]: any;
+  },
+> = {
+  [K in keyof T]: true extends T[K]['required'] ? K : never;
+}[keyof T];
+
+// @public (undocumented)
+type Push<T extends any[], V> = [...T, V];
+
+// @public (undocumented)
+interface QueryObject extends ParameterObject {
+  // (undocumented)
+  in: 'query';
+  // (undocumented)
+  style?: 'form' | 'deepObject' | 'pipeDelimited' | 'spaceDelimited';
+}
+
+// @public (undocumented)
+type QuerySchema<
+  Doc extends RequiredDoc,
+  Path extends PathTemplate<Extract<keyof Doc['paths'], string>>,
+  Method extends DocPathMethod<Doc, Path>,
+> = ParametersSchema<Doc, DocPath<Doc, Path>, Method, ImmutableQueryObject>;
+
+// @public (undocumented)
+type RequestBody<
+  Doc extends RequiredDoc,
+  Path extends Extract<keyof Doc['paths'], string>,
+  Method extends keyof Doc['paths'][Path],
+> = DocOperation<
+  Doc,
+  Path,
+  Method
+>['requestBody'] extends ImmutableReferenceObject
+  ? 'requestBodies' extends ComponentTypes<Doc>
+    ? ComponentRef<
+        Doc,
+        'requestBodies',
+        DocOperation<Doc, Path, Method>['requestBody']
+      >
+    : never
+  : DocOperation<Doc, Path, Method>['requestBody'];
+
+// @public (undocumented)
+type RequestBodySchema<
+  Doc extends RequiredDoc,
+  Path extends DocPathTemplate<Doc>,
+  Method extends DocPathMethod<Doc, Path>,
+> = RequestBody<
+  Doc,
+  DocPath<Doc, Path>,
+  Method
+> extends ImmutableRequestBodyObject
+  ? ObjectWithContentSchema<Doc, RequestBody<Doc, DocPath<Doc, Path>, Method>>
+  : never;
+
+// @public
+type RequestBodyToJsonSchema<
+  Doc extends RequiredDoc,
+  Path extends PathTemplate<Extract<keyof Doc['paths'], string>>,
+  Method extends DocPathMethod<Doc, Path>,
+> = ToTypeSafe<RequestBodySchema<Doc, Path, Method>>;
+
+// @public
+type RequiredDoc = Pick<ImmutableOpenAPIObject, 'paths' | 'components'>;
+
+// @public (undocumented)
+type RequiredMap<
+  T extends {
+    [key: string]: any;
+  },
+> = {
+  [P in Exclude<PickRequiredKeys<T>, undefined>]: NonNullable<T[P]>;
+};
+
+// @public (undocumented)
+type ResolveDocParameterSchema<
+  Doc extends RequiredDoc,
+  Schema extends ImmutableParameterObject['schema'],
+> = Schema extends ImmutableReferenceObject
+  ? 'parameters' extends ComponentTypes<Doc>
+    ? ComponentRef<Doc, 'parameters', Schema>
+    : never
+  : Schema;
+
+// @public (undocumented)
+type Response_2<
+  Doc extends RequiredDoc,
+  Path extends keyof Doc['paths'],
+  Method extends keyof Doc['paths'][Path],
+  StatusCode extends keyof DocOperation<Doc, Path, Method>['responses'],
+> = DocOperation<
+  Doc,
+  Path,
+  Method
+>['responses'][StatusCode] extends ImmutableReferenceObject
+  ? 'responses' extends ComponentTypes<Doc>
+    ? ComponentRef<
+        Doc,
+        'responses',
+        DocOperation<Doc, Path, Method>['responses'][StatusCode]
+      >
+    : never
+  : DocOperation<Doc, Path, Method>['responses'][StatusCode];
+
+// @public
+type ResponseBodyToJsonSchema<
+  Doc extends RequiredDoc,
+  Path extends PathTemplate<Extract<keyof Doc['paths'], string>>,
+  Method extends DocPathMethod<Doc, Path>,
+> = ToTypeSafe<ValueOf<ResponseSchemas<Doc, Path, Method>>>;
+
+// @public (undocumented)
+type ResponseSchemas<
+  Doc extends RequiredDoc,
+  Path extends DocPathTemplate<Doc>,
+  Method extends DocPathMethod<Doc, Path>,
+> = {
+  [StatusCode in keyof DocOperation<
+    Doc,
+    Path,
+    Method
+  >['responses']]: Response_2<
+    Doc,
+    Path,
+    Method,
+    StatusCode
+  > extends ImmutableResponseObject
+    ? ObjectWithContentSchema<Doc, Response_2<Doc, Path, Method, StatusCode>>
+    : never;
+};
+
+// @public (undocumented)
+type SchemaRef<Doc extends RequiredDoc, Schema> = Schema extends {
+  $ref: `#/components/schemas/${infer Name}`;
+}
+  ? 'schemas' extends keyof Doc['components']
+    ? Name extends keyof Doc['components']['schemas']
+      ? SchemaRef<Doc, Doc['components']['schemas'][Name]>
+      : never
+    : never
+  : {
+      [Key in keyof Schema]: SchemaRef<Doc, Schema[Key]>;
+    };
+
+// @public (undocumented)
+type ToTypeSafe<T> = UnknownIfNever<ConvertAll<TuplifyUnion<T>>[number]>;
+
+// @public (undocumented)
+type TuplifyUnion<
+  T,
+  L = LastOf<T>,
+  N = [T] extends [never] ? true : false,
+> = true extends N ? [] : Push<TuplifyUnion<Exclude<T, L>>, L>;
+
+// @public
+type UnionToIntersection<U> = (U extends any ? (k: U) => void : never) extends (
+  k: infer I,
+) => void
+  ? I
+  : never;
+
+// @public (undocumented)
+type UnknownIfNever<P> = [P] extends [never] ? unknown : P;
+
+// @public
+type ValueOf<T> = T[keyof T];
 ```
diff --git a/packages/backend-openapi-utils/src/index.ts b/packages/backend-openapi-utils/src/index.ts
index 3aab4ab1d1..c92bb0741a 100644
--- a/packages/backend-openapi-utils/src/index.ts
+++ b/packages/backend-openapi-utils/src/index.ts
@@ -19,6 +19,7 @@
  *
  * @packageDocumentation
  */
+import * as core from './types';
 
+export { core };
 export type { ApiRouter } from './router';
-export * from './types';
diff --git a/packages/backend-openapi-utils/src/router.ts b/packages/backend-openapi-utils/src/router.ts
index de2dc5b72a..253fc1596e 100644
--- a/packages/backend-openapi-utils/src/router.ts
+++ b/packages/backend-openapi-utils/src/router.ts
@@ -14,26 +14,26 @@
  * limitations under the License.
  */
 import { Router } from 'express';
-import { core } from './types';
+import { DocRequestMatcher, RequiredDoc } from './types';
 
 /**
  * Typed Express router based on an OpenAPI 3.1 spec.
  * @public
  */
-export interface ApiRouter<Doc extends core.Spec> extends Router {
-  get: core.RequestMatcher<Doc, this, 'get'>;
+export interface ApiRouter<Doc extends RequiredDoc> extends Router {
+  get: DocRequestMatcher<Doc, this, 'get'>;
 
-  post: core.RequestMatcher<Doc, this, 'post'>;
+  post: DocRequestMatcher<Doc, this, 'post'>;
 
-  all: core.RequestMatcher<Doc, this, 'all'>;
+  all: DocRequestMatcher<Doc, this, 'all'>;
 
-  put: core.RequestMatcher<Doc, this, 'put'>;
+  put: DocRequestMatcher<Doc, this, 'put'>;
 
-  delete: core.RequestMatcher<Doc, this, 'delete'>;
+  delete: DocRequestMatcher<Doc, this, 'delete'>;
 
-  patch: core.RequestMatcher<Doc, this, 'patch'>;
+  patch: DocRequestMatcher<Doc, this, 'patch'>;
 
-  options: core.RequestMatcher<Doc, this, 'options'>;
+  options: DocRequestMatcher<Doc, this, 'options'>;
 
-  head: core.RequestMatcher<Doc, this, 'head'>;
+  head: DocRequestMatcher<Doc, this, 'head'>;
 }
diff --git a/packages/backend-openapi-utils/src/types/common.ts b/packages/backend-openapi-utils/src/types/common.ts
index aea8ae2543..5568ed795c 100644
--- a/packages/backend-openapi-utils/src/types/common.ts
+++ b/packages/backend-openapi-utils/src/types/common.ts
@@ -27,13 +27,18 @@ import {
 
 /**
  * Basic OpenAPI spec with paths and components properties enforced.
+ * @public
  */
 export type RequiredDoc = Pick<ImmutableOpenAPIObject, 'paths' | 'components'>;
 
+/**
+ * @public
+ */
 export type PathDoc = Pick<ImmutableOpenAPIObject, 'paths'>;
 
 /**
  * Get value types of `T`.
+ * @public
  */
 export type ValueOf<T> = T[keyof T];
 
@@ -45,6 +50,8 @@ export type ValueOf<T> = T[keyof T];
  * const path: PathTemplate<"/posts/{postId}/comments/{commentId}"> = "/posts/:postId/comments/:commentId";
  * const pathWithoutParams: PathTemplate<"/posts/comments"> = "/posts/comments";
  * ```
+ *
+ * @public
  */
 export type PathTemplate<Path extends string> =
   Path extends `${infer Prefix}{${infer PathName}}${infer Suffix}`
@@ -64,6 +71,8 @@ export type PathTemplate<Path extends string> =
  * const specPathWithParams: DocPath<typeof spec, "/posts/:postId/comments/:commentId"> = "/posts/{postId}/comments/{commentId}";
  * const specPathWithoutParams: DocPath<typeof spec, "/posts/comments"> = "/posts/comments";
  * ```
+ *
+ * @public
  */
 export type DocPath<
   Doc extends PathDoc,
@@ -75,15 +84,24 @@ export type DocPath<
   >]: Path extends PathTemplate<Template> ? Template : never;
 }>;
 
+/**
+ * @public
+ */
 export type DocPathTemplate<Doc extends PathDoc> = PathTemplate<
   Extract<keyof Doc['paths'], string>
 >;
 
+/**
+ * @public
+ */
 export type DocPathMethod<
   Doc extends Pick<RequiredDoc, 'paths'>,
   Path extends DocPathTemplate<Doc>,
 > = keyof Doc['paths'][DocPath<Doc, Path>];
 
+/**
+ * @public
+ */
 export type MethodAwareDocPath<
   Doc extends PathDoc,
   Path extends PathTemplate<Extract<keyof Doc['paths'], string>>,
@@ -99,17 +117,26 @@ export type MethodAwareDocPath<
     : never;
 }>;
 
+/**
+ * @public
+ */
 export type DocOperation<
   Doc extends RequiredDoc,
   Path extends keyof Doc['paths'],
   Method extends keyof Doc['paths'][Path],
 > = Doc['paths'][Path][Method];
 
+/**
+ * @public
+ */
 export type ComponentTypes<Doc extends RequiredDoc> = Extract<
   keyof Doc['components'],
   string
 >;
 
+/**
+ * @public
+ */
 export type ComponentRef<
   Doc extends RequiredDoc,
   Type extends ComponentTypes<Doc>,
@@ -122,6 +149,9 @@ export type ComponentRef<
     : never
   : never;
 
+/**
+ * @public
+ */
 export type SchemaRef<Doc extends RequiredDoc, Schema> = Schema extends {
   $ref: `#/components/schemas/${infer Name}`;
 }
@@ -132,6 +162,9 @@ export type SchemaRef<Doc extends RequiredDoc, Schema> = Schema extends {
     : never
   : { [Key in keyof Schema]: SchemaRef<Doc, Schema[Key]> };
 
+/**
+ * @public
+ */
 export type ObjectWithContentSchema<
   Doc extends RequiredDoc,
   Object extends { content?: ImmutableContentObject },
@@ -143,6 +176,8 @@ export type ObjectWithContentSchema<
  * From {@link https://stackoverflow.com/questions/71393738/typescript-intersection-not-union-type-from-json-schema}
  *
  * StackOverflow says not to do this, but union types aren't possible any other way.
+ *
+ * @public
  */
 export type UnionToIntersection<U> = (
   U extends any ? (k: U) => void : never
@@ -150,20 +185,32 @@ export type UnionToIntersection<U> = (
   ? I
   : never;
 
+/**
+ * @public
+ */
 export type LastOf<T> = UnionToIntersection<
   T extends any ? () => T : never
 > extends () => infer R
   ? R
   : never;
 
+/**
+ * @public
+ */
 export type Push<T extends any[], V> = [...T, V];
 
+/**
+ * @public
+ */
 export type TuplifyUnion<
   T,
   L = LastOf<T>,
   N = [T] extends [never] ? true : false,
 > = true extends N ? [] : Push<TuplifyUnion<Exclude<T, L>>, L>;
 
+/**
+ * @public
+ */
 export type ConvertAll<T, R extends ReadonlyArray<unknown> = []> = T extends [
   infer First extends JSONSchema7,
   ...infer Rest,
@@ -171,15 +218,27 @@ export type ConvertAll<T, R extends ReadonlyArray<unknown> = []> = T extends [
   ? ConvertAll<Rest, [...R, FromSchema<First>]>
   : R;
 
+/**
+ * @public
+ */
 export type UnknownIfNever<P> = [P] extends [never] ? unknown : P;
 
+/**
+ * @public
+ */
 export type ToTypeSafe<T> = UnknownIfNever<ConvertAll<TuplifyUnion<T>>[number]>;
 
+/**
+ * @public
+ */
 export type DiscriminateUnion<T, K extends keyof T, V extends T[K]> = Extract<
   T,
   Record<K, V>
 >;
 
+/**
+ * @public
+ */
 export type MapDiscriminatedUnion<
   T extends Record<K, string>,
   K extends keyof T,
@@ -187,23 +246,41 @@ export type MapDiscriminatedUnion<
   [V in T[K]]: DiscriminateUnion<T, K, V>;
 };
 
+/**
+ * @public
+ */
 export type PickOptionalKeys<T extends { [key: string]: any }> = {
   [K in keyof T]: true extends T[K]['required'] ? never : K;
 }[keyof T];
 
+/**
+ * @public
+ */
 export type PickRequiredKeys<T extends { [key: string]: any }> = {
   [K in keyof T]: true extends T[K]['required'] ? K : never;
 }[keyof T];
 
+/**
+ * @public
+ */
 export type OptionalMap<T extends { [key: string]: any }> = {
   [P in Exclude<PickOptionalKeys<T>, undefined>]?: NonNullable<T[P]>;
 };
 
+/**
+ * @public
+ */
 export type RequiredMap<T extends { [key: string]: any }> = {
   [P in Exclude<PickRequiredKeys<T>, undefined>]: NonNullable<T[P]>;
 };
 
+/**
+ * @public
+ */
 export type FullMap<T extends { [key: string]: any }> = RequiredMap<T> &
   OptionalMap<T>;
 
+/**
+ * @public
+ */
 export type Filter<T, U> = T extends U ? T : never;
diff --git a/packages/backend-openapi-utils/src/types/express.ts b/packages/backend-openapi-utils/src/types/express.ts
index 1ab262352d..7f553f8217 100644
--- a/packages/backend-openapi-utils/src/types/express.ts
+++ b/packages/backend-openapi-utils/src/types/express.ts
@@ -21,8 +21,9 @@ import { ResponseBodyToJsonSchema } from './responses';
 
 /**
  * Typed express request handler.
+ * @public
  */
-type DocRequestHandler<
+export type DocRequestHandler<
   Doc extends RequiredDoc,
   Path extends DocPathTemplate<Doc>,
   Method extends keyof Doc['paths'][Path],
@@ -36,8 +37,9 @@ type DocRequestHandler<
 
 /**
  * Typed express error handler / request handler union type.
+ * @public
  */
-type DocRequestHandlerParams<
+export type DocRequestHandlerParams<
   Doc extends RequiredDoc,
   Path extends DocPathTemplate<Doc>,
   Method extends keyof Doc['paths'][Path],
@@ -51,6 +53,7 @@ type DocRequestHandlerParams<
 
 /**
  * Superset of the express router path matcher that enforces typed request and response bodies.
+ * @public
  */
 export interface DocRequestMatcher<
   Doc extends RequiredDoc,
diff --git a/packages/backend-openapi-utils/src/types/immutable.ts b/packages/backend-openapi-utils/src/types/immutable.ts
index 400d4e4b4b..3b253133d8 100644
--- a/packages/backend-openapi-utils/src/types/immutable.ts
+++ b/packages/backend-openapi-utils/src/types/immutable.ts
@@ -31,6 +31,8 @@ import type {
 /**
  * From {@link https://github.com/microsoft/TypeScript/issues/13923#issuecomment-653675557}, allows
  *  us to convert from `as const` to the various OpenAPI types documented in `openapi3-ts`.
+ *
+ * @public
  */
 export type Immutable<T> = T extends
   | Function
@@ -46,46 +48,93 @@ export type Immutable<T> = T extends
   ? ReadonlySet<Immutable<S>>
   : { readonly [P in keyof T]: Immutable<T[P]> };
 
+/**
+ * @public
+ */
 export type ImmutableObject<T> = { readonly [K in keyof T]: Immutable<T[K]> };
 
+/**
+ * @public
+ */
 export type ImmutableReferenceObject = ImmutableObject<ReferenceObject>;
 
+/**
+ * @public
+ */
 export type ImmutableOpenAPIObject = ImmutableObject<OpenAPIObject>;
 
+/**
+ * @public
+ */
 export type ImmutableContentObject = ImmutableObject<ContentObject>;
 
+/**
+ * @public
+ */
 export type ImmutableRequestBodyObject = ImmutableObject<RequestBodyObject>;
 
+/**
+ * @public
+ */
 export type ImmutableResponseObject = ImmutableObject<ResponseObject>;
 
+/**
+ * @public
+ */
 export type ImmutableParameterObject = ImmutableObject<ParameterObject>;
 
-interface HeaderObject extends ParameterObject {
+/**
+ * @public
+ */
+export interface HeaderObject extends ParameterObject {
   in: 'header';
   style: 'simple';
 }
 
+/**
+ * @public
+ */
 export type ImmutableHeaderObject = ImmutableObject<HeaderObject>;
 
-interface CookieObject extends ParameterObject {
+/**
+ * @public
+ */
+export interface CookieObject extends ParameterObject {
   in: 'cookie';
   style?: 'form';
 }
 
+/**
+ * @public
+ */
 export type ImmutableCookieObject = ImmutableObject<CookieObject>;
 
-interface QueryObject extends ParameterObject {
+/**
+ * @public
+ */
+export interface QueryObject extends ParameterObject {
   in: 'query';
   style?: 'form' | 'deepObject' | 'pipeDelimited' | 'spaceDelimited';
 }
 
+/**
+ * @public
+ */
 export type ImmutableQueryObject = ImmutableObject<QueryObject>;
 
-interface PathObject extends ParameterObject {
+/**
+ * @public
+ */
+export interface PathObject extends ParameterObject {
   in: 'path';
   style?: 'simple' | 'label' | 'matrix';
 }
-
+/**
+ * @public
+ */
 export type ImmutablePathObject = ImmutableObject<PathObject>;
 
+/**
+ * @public
+ */
 export type ImmutableSchemaObject = ImmutableObject<SchemaObject>;
diff --git a/packages/backend-openapi-utils/src/types/index.ts b/packages/backend-openapi-utils/src/types/index.ts
index 5fcd90d558..98e58f68ad 100644
--- a/packages/backend-openapi-utils/src/types/index.ts
+++ b/packages/backend-openapi-utils/src/types/index.ts
@@ -14,32 +14,9 @@
  * limitations under the License.
  */
 
-import type { RequiredDoc } from './common';
-import type { DocRequestMatcher } from './express';
-
-/**
- * @public
- */
-export namespace core {
-  /**
-   * @internal
-   */
-  export type Spec = RequiredDoc;
-
-  /**
-   * @internal
-   */
-  export type RequestMatcher<
-    Doc extends RequiredDoc,
-    T,
-    Method extends
-      | 'all'
-      | 'get'
-      | 'post'
-      | 'put'
-      | 'delete'
-      | 'patch'
-      | 'options'
-      | 'head',
-  > = DocRequestMatcher<Doc, T, Method>;
-}
+export * from './common';
+export * from './express';
+export * from './immutable';
+export * from './params';
+export * from './requests';
+export * from './responses';
diff --git a/packages/backend-openapi-utils/src/types/params.ts b/packages/backend-openapi-utils/src/types/params.ts
index 1a75775aab..dce743e6e8 100644
--- a/packages/backend-openapi-utils/src/types/params.ts
+++ b/packages/backend-openapi-utils/src/types/params.ts
@@ -37,7 +37,10 @@ import {
 } from './common';
 import { FromSchema, JSONSchema7 } from 'json-schema-to-ts';
 
-type DocParameter<
+/**
+ * @public
+ */
+export type DocParameter<
   Doc extends RequiredDoc,
   Path extends Extract<keyof Doc['paths'], string>,
   Method extends keyof Doc['paths'][Path],
@@ -56,7 +59,10 @@ type DocParameter<
     : never
   : DocOperation<Doc, Path, Method>['parameters'][Parameter];
 
-type DocParameters<
+/**
+ * @public
+ */
+export type DocParameters<
   Doc extends RequiredDoc,
   Path extends Extract<keyof Doc['paths'], string>,
   Method extends keyof Doc['paths'][Path],
@@ -70,7 +76,10 @@ type DocParameters<
     }
   : never;
 
-type ResolveDocParameterSchema<
+/**
+ * @public
+ */
+export type ResolveDocParameterSchema<
   Doc extends RequiredDoc,
   Schema extends ImmutableParameterObject['schema'],
 > = Schema extends ImmutableReferenceObject
@@ -79,7 +88,10 @@ type ResolveDocParameterSchema<
     : never
   : Schema;
 
-type ParameterSchema<
+/**
+ * @public
+ */
+export type ParameterSchema<
   Doc extends RequiredDoc,
   Schema extends ImmutableParameterObject['schema'],
 > = ResolveDocParameterSchema<Doc, Schema> extends infer R
@@ -90,7 +102,10 @@ type ParameterSchema<
     : never
   : never;
 
-type MapToSchema<
+/**
+ * @public
+ */
+export type MapToSchema<
   Doc extends RequiredDoc,
   T extends Record<string, ImmutableParameterObject>,
 > = {
@@ -99,7 +114,10 @@ type MapToSchema<
     : never;
 };
 
-type ParametersSchema<
+/**
+ * @public
+ */
+export type ParametersSchema<
   Doc extends RequiredDoc,
   Path extends Extract<keyof Doc['paths'], string>,
   Method extends keyof Doc['paths'][Path],
@@ -116,24 +134,36 @@ type ParametersSchema<
     >
   : never;
 
+/**
+ * @public
+ */
 export type HeaderSchema<
   Doc extends RequiredDoc,
   Path extends PathTemplate<Extract<keyof Doc['paths'], string>>,
   Method extends DocPathMethod<Doc, Path>,
 > = ParametersSchema<Doc, DocPath<Doc, Path>, Method, ImmutableHeaderObject>;
 
+/**
+ * @public
+ */
 export type CookieSchema<
   Doc extends RequiredDoc,
   Path extends PathTemplate<Extract<keyof Doc['paths'], string>>,
   Method extends DocPathMethod<Doc, Path>,
 > = ParametersSchema<Doc, DocPath<Doc, Path>, Method, ImmutableCookieObject>;
 
+/**
+ * @public
+ */
 export type PathSchema<
   Doc extends RequiredDoc,
   Path extends PathTemplate<Extract<keyof Doc['paths'], string>>,
   Method extends DocPathMethod<Doc, Path>,
 > = ParametersSchema<Doc, DocPath<Doc, Path>, Method, ImmutablePathObject>;
 
+/**
+ * @public
+ */
 export type QuerySchema<
   Doc extends RequiredDoc,
   Path extends PathTemplate<Extract<keyof Doc['paths'], string>>,
diff --git a/packages/backend-openapi-utils/src/types/requests.ts b/packages/backend-openapi-utils/src/types/requests.ts
index 71e25b91bd..e6542e186d 100644
--- a/packages/backend-openapi-utils/src/types/requests.ts
+++ b/packages/backend-openapi-utils/src/types/requests.ts
@@ -35,7 +35,10 @@ import {
   ImmutableRequestBodyObject,
 } from './immutable';
 
-type RequestBody<
+/**
+ * @public
+ */
+export type RequestBody<
   Doc extends RequiredDoc,
   Path extends Extract<keyof Doc['paths'], string>,
   Method extends keyof Doc['paths'][Path],
@@ -53,7 +56,10 @@ type RequestBody<
     : never
   : DocOperation<Doc, Path, Method>['requestBody'];
 
-type RequestBodySchema<
+/**
+ * @public
+ */
+export type RequestBodySchema<
   Doc extends RequiredDoc,
   Path extends DocPathTemplate<Doc>,
   Method extends DocPathMethod<Doc, Path>,
@@ -67,6 +73,7 @@ type RequestBodySchema<
 
 /**
  * Transform the OpenAPI request body schema to a typesafe JSON schema.
+ * @public
  */
 export type RequestBodyToJsonSchema<
   Doc extends RequiredDoc,
diff --git a/packages/backend-openapi-utils/src/types/responses.ts b/packages/backend-openapi-utils/src/types/responses.ts
index ef60fb873f..01e4a12aba 100644
--- a/packages/backend-openapi-utils/src/types/responses.ts
+++ b/packages/backend-openapi-utils/src/types/responses.ts
@@ -24,7 +24,6 @@ import type {
   ObjectWithContentSchema,
   RequiredDoc,
   DocOperation,
-  DocPath,
   DocPathMethod,
   DocPathTemplate,
   PathTemplate,
@@ -33,11 +32,14 @@ import type {
 } from './common';
 import { ImmutableReferenceObject, ImmutableResponseObject } from './immutable';
 
-type Response<
+/**
+ * @public
+ */
+export type Response<
   Doc extends RequiredDoc,
   Path extends keyof Doc['paths'],
   Method extends keyof Doc['paths'][Path],
-  StatusCode extends keyof Doc['paths'][Path]['responses'],
+  StatusCode extends keyof DocOperation<Doc, Path, Method>['responses'],
 > = DocOperation<
   Doc,
   Path,
@@ -52,43 +54,27 @@ type Response<
     : never
   : DocOperation<Doc, Path, Method>['responses'][StatusCode];
 
-type Responses<
+/**
+ * @public
+ */
+export type ResponseSchemas<
   Doc extends RequiredDoc,
-  Path extends keyof Doc['paths'],
-  Method extends keyof Doc['paths'][Path],
+  Path extends DocPathTemplate<Doc>,
+  Method extends DocPathMethod<Doc, Path>,
 > = {
   [StatusCode in keyof DocOperation<Doc, Path, Method>['responses']]: Response<
     Doc,
     Path,
     Method,
     StatusCode
-  >;
-};
-
-type ResponseSchema<
-  Doc extends RequiredDoc,
-  Object extends ImmutableResponseObject,
-> = ObjectWithContentSchema<Doc, Object>;
-
-type ResponseSchemas<
-  Doc extends RequiredDoc,
-  Path extends DocPathTemplate<Doc>,
-  Method extends DocPathMethod<Doc, Path>,
-> = {
-  [StatusCode in keyof Responses<Doc, DocPath<Doc, Path>, Method>]: Responses<
-    Doc,
-    DocPath<Doc, Path>,
-    Method
-  >[StatusCode] extends ImmutableResponseObject
-    ? ResponseSchema<
-        Doc,
-        Responses<Doc, DocPath<Doc, Path>, Method>[StatusCode]
-      >
+  > extends ImmutableResponseObject
+    ? ObjectWithContentSchema<Doc, Response<Doc, Path, Method, StatusCode>>
     : never;
 };
 
 /**
  * Transform the OpenAPI request body schema to a typesafe JSON schema.
+ * @public
  */
 export type ResponseBodyToJsonSchema<
   Doc extends RequiredDoc,

From 8b1e62a4d4235e89cdb7aeea10f330a8f673cbba Mon Sep 17 00:00:00 2001
From: Aramis Sennyey <sennyeya@amazon.com>
Date: Mon, 3 Apr 2023 14:11:04 -0400
Subject: [PATCH 58/61] Fix import.

Signed-off-by: Aramis Sennyey <sennyeya@amazon.com>
---
 packages/backend-openapi-utils/src/types/express.ts | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/backend-openapi-utils/src/types/express.ts b/packages/backend-openapi-utils/src/types/express.ts
index 7f553f8217..b0020dab37 100644
--- a/packages/backend-openapi-utils/src/types/express.ts
+++ b/packages/backend-openapi-utils/src/types/express.ts
@@ -13,7 +13,7 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-import core from 'express-serve-static-core';
+import type core from 'express-serve-static-core';
 import { DocPathTemplate, MethodAwareDocPath, RequiredDoc } from './common';
 import { PathSchema, QuerySchema } from './params';
 import { RequestBodyToJsonSchema } from './requests';

From d1a9e116fc4480358425b6a00988da587b2b2493 Mon Sep 17 00:00:00 2001
From: Aramis Sennyey <sennyeya@amazon.com>
Date: Mon, 3 Apr 2023 15:05:32 -0400
Subject: [PATCH 59/61] Fix API report.

Signed-off-by: Aramis Sennyey <sennyeya@amazon.com>
---
 packages/backend-openapi-utils/api-report.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/backend-openapi-utils/api-report.md b/packages/backend-openapi-utils/api-report.md
index af102d4df8..61f668ad5a 100644
--- a/packages/backend-openapi-utils/api-report.md
+++ b/packages/backend-openapi-utils/api-report.md
@@ -4,7 +4,7 @@
 
 ```ts
 import type { ContentObject } from 'openapi3-ts';
-import { default as core_2 } from 'express-serve-static-core';
+import type { default as core_2 } from 'express-serve-static-core';
 import { FromSchema } from 'json-schema-to-ts';
 import { JSONSchema7 } from 'json-schema-to-ts';
 import type { OpenAPIObject } from 'openapi3-ts';

From d7d059e66517b737654e30b9bc1f46e9d3c7865f Mon Sep 17 00:00:00 2001
From: Aramis Sennyey <sennyeya@amazon.com>
Date: Mon, 3 Apr 2023 16:43:44 -0400
Subject: [PATCH 60/61] Fix dependency issue.

Signed-off-by: Aramis Sennyey <sennyeya@amazon.com>
---
 packages/backend-openapi-utils/package.json | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/packages/backend-openapi-utils/package.json b/packages/backend-openapi-utils/package.json
index 5a06c48ffc..a9131e0e8c 100644
--- a/packages/backend-openapi-utils/package.json
+++ b/packages/backend-openapi-utils/package.json
@@ -24,14 +24,14 @@
     "postpack": "backstage-cli package postpack"
   },
   "devDependencies": {
-    "@backstage/cli": "workspace:^",
-    "@types/express-serve-static-core": "^4.17.5"
+    "@backstage/cli": "workspace:^"
   },
   "files": [
     "dist"
   ],
   "dependencies": {
     "@types/express": "^4.17.6",
+    "@types/express-serve-static-core": "^4.17.5",
     "express": "^4.17.1",
     "express-promise-router": "^4.1.0",
     "json-schema-to-ts": "^2.6.2",

From cd9296f1002da65950da7c66a420bcd7db9fff13 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Fredrik=20Adel=C3=B6w?= <freben@gmail.com>
Date: Wed, 5 Apr 2023 14:25:48 +0200
Subject: [PATCH 61/61] minor fixup
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Signed-off-by: Fredrik Adelöw <freben@gmail.com>
---
 packages/backend-openapi-utils/api-report.md  | 146 ++---
 packages/backend-openapi-utils/src/index.ts   |   4 +-
 .../repo-tools/src/commands/openapi/verify.ts |   6 +-
 yarn.lock                                     | 499 +++++-------------
 4 files changed, 200 insertions(+), 455 deletions(-)

diff --git a/packages/backend-openapi-utils/api-report.md b/packages/backend-openapi-utils/api-report.md
index 61f668ad5a..180a7846ed 100644
--- a/packages/backend-openapi-utils/api-report.md
+++ b/packages/backend-openapi-utils/api-report.md
@@ -4,7 +4,7 @@
 
 ```ts
 import type { ContentObject } from 'openapi3-ts';
-import type { default as core_2 } from 'express-serve-static-core';
+import type core from 'express-serve-static-core';
 import { FromSchema } from 'json-schema-to-ts';
 import { JSONSchema7 } from 'json-schema-to-ts';
 import type { OpenAPIObject } from 'openapi3-ts';
@@ -79,76 +79,6 @@ type CookieSchema<
   Method extends DocPathMethod<Doc, Path>,
 > = ParametersSchema<Doc, DocPath<Doc, Path>, Method, ImmutableCookieObject>;
 
-declare namespace core {
-  export {
-    RequiredDoc,
-    PathDoc,
-    ValueOf,
-    PathTemplate,
-    DocPath,
-    DocPathTemplate,
-    DocPathMethod,
-    MethodAwareDocPath,
-    DocOperation,
-    ComponentTypes,
-    ComponentRef,
-    SchemaRef,
-    ObjectWithContentSchema,
-    UnionToIntersection,
-    LastOf,
-    Push,
-    TuplifyUnion,
-    ConvertAll,
-    UnknownIfNever,
-    ToTypeSafe,
-    DiscriminateUnion,
-    MapDiscriminatedUnion,
-    PickOptionalKeys,
-    PickRequiredKeys,
-    OptionalMap,
-    RequiredMap,
-    FullMap,
-    Filter,
-    DocRequestHandler,
-    DocRequestHandlerParams,
-    DocRequestMatcher,
-    Immutable,
-    ImmutableObject,
-    ImmutableReferenceObject,
-    ImmutableOpenAPIObject,
-    ImmutableContentObject,
-    ImmutableRequestBodyObject,
-    ImmutableResponseObject,
-    ImmutableParameterObject,
-    HeaderObject,
-    ImmutableHeaderObject,
-    CookieObject,
-    ImmutableCookieObject,
-    QueryObject,
-    ImmutableQueryObject,
-    PathObject,
-    ImmutablePathObject,
-    ImmutableSchemaObject,
-    DocParameter,
-    DocParameters,
-    ResolveDocParameterSchema,
-    ParameterSchema,
-    MapToSchema,
-    ParametersSchema,
-    HeaderSchema,
-    CookieSchema,
-    PathSchema,
-    QuerySchema,
-    RequestBody,
-    RequestBodySchema,
-    RequestBodyToJsonSchema,
-    Response_2 as Response,
-    ResponseSchemas,
-    ResponseBodyToJsonSchema,
-  };
-}
-export { core };
-
 // @public (undocumented)
 type DiscriminateUnion<T, K extends keyof T, V extends T[K]> = Extract<
   T,
@@ -224,7 +154,7 @@ type DocRequestHandler<
   Doc extends RequiredDoc,
   Path extends DocPathTemplate<Doc>,
   Method extends keyof Doc['paths'][Path],
-> = core_2.RequestHandler<
+> = core.RequestHandler<
   PathSchema<Doc, Path, Method>,
   ResponseBodyToJsonSchema<Doc, Path, Method>,
   RequestBodyToJsonSchema<Doc, Path, Method>,
@@ -237,7 +167,7 @@ type DocRequestHandlerParams<
   Doc extends RequiredDoc,
   Path extends DocPathTemplate<Doc>,
   Method extends keyof Doc['paths'][Path],
-> = core_2.RequestHandlerParams<
+> = core.RequestHandlerParams<
   PathSchema<Doc, Path, Method>,
   ResponseBodyToJsonSchema<Doc, Path, Method>,
   RequestBodyToJsonSchema<Doc, Path, Method>,
@@ -351,6 +281,76 @@ type ImmutableResponseObject = ImmutableObject<ResponseObject>;
 // @public (undocumented)
 type ImmutableSchemaObject = ImmutableObject<SchemaObject>;
 
+declare namespace internal {
+  export {
+    RequiredDoc,
+    PathDoc,
+    ValueOf,
+    PathTemplate,
+    DocPath,
+    DocPathTemplate,
+    DocPathMethod,
+    MethodAwareDocPath,
+    DocOperation,
+    ComponentTypes,
+    ComponentRef,
+    SchemaRef,
+    ObjectWithContentSchema,
+    UnionToIntersection,
+    LastOf,
+    Push,
+    TuplifyUnion,
+    ConvertAll,
+    UnknownIfNever,
+    ToTypeSafe,
+    DiscriminateUnion,
+    MapDiscriminatedUnion,
+    PickOptionalKeys,
+    PickRequiredKeys,
+    OptionalMap,
+    RequiredMap,
+    FullMap,
+    Filter,
+    DocRequestHandler,
+    DocRequestHandlerParams,
+    DocRequestMatcher,
+    Immutable,
+    ImmutableObject,
+    ImmutableReferenceObject,
+    ImmutableOpenAPIObject,
+    ImmutableContentObject,
+    ImmutableRequestBodyObject,
+    ImmutableResponseObject,
+    ImmutableParameterObject,
+    HeaderObject,
+    ImmutableHeaderObject,
+    CookieObject,
+    ImmutableCookieObject,
+    QueryObject,
+    ImmutableQueryObject,
+    PathObject,
+    ImmutablePathObject,
+    ImmutableSchemaObject,
+    DocParameter,
+    DocParameters,
+    ResolveDocParameterSchema,
+    ParameterSchema,
+    MapToSchema,
+    ParametersSchema,
+    HeaderSchema,
+    CookieSchema,
+    PathSchema,
+    QuerySchema,
+    RequestBody,
+    RequestBodySchema,
+    RequestBodyToJsonSchema,
+    Response_2 as Response,
+    ResponseSchemas,
+    ResponseBodyToJsonSchema,
+  };
+}
+export { internal };
+
 // @public (undocumented)
 type LastOf<T> = UnionToIntersection<
   T extends any ? () => T : never
diff --git a/packages/backend-openapi-utils/src/index.ts b/packages/backend-openapi-utils/src/index.ts
index c92bb0741a..f8fdcff16b 100644
--- a/packages/backend-openapi-utils/src/index.ts
+++ b/packages/backend-openapi-utils/src/index.ts
@@ -19,7 +19,7 @@
  *
  * @packageDocumentation
  */
-import * as core from './types';
+import * as internal from './types';
 
-export { core };
+export { internal };
 export type { ApiRouter } from './router';
diff --git a/packages/repo-tools/src/commands/openapi/verify.ts b/packages/repo-tools/src/commands/openapi/verify.ts
index 8febe11cf5..f6dda66738 100644
--- a/packages/repo-tools/src/commands/openapi/verify.ts
+++ b/packages/repo-tools/src/commands/openapi/verify.ts
@@ -45,11 +45,9 @@ async function verify(directoryPath: string) {
     throw new Error(`\`${TS_SCHEMA_PATH}\` needs to have a default export.`);
   }
   if (!isEqual(schema.default, yaml)) {
+    const path = relativePath(cliPaths.targetRoot, directoryPath);
     throw new Error(
-      `\`${YAML_SCHEMA_PATH}\` and \`${TS_SCHEMA_PATH}\` do not match. Please run \`yarn --cwd ${relativePath(
-        cliPaths.targetRoot,
-        directoryPath,
-      )} schema:openapi:generate\` to regenerate \`${TS_SCHEMA_PATH}\`.`,
+      `\`${YAML_SCHEMA_PATH}\` and \`${TS_SCHEMA_PATH}\` do not match. Please run \`yarn backstage-repo-tools schema:openapi:generate ${path}\` to regenerate \`${TS_SCHEMA_PATH}\`.`,
     );
   }
 }
diff --git a/yarn.lock b/yarn.lock
index 6eb6bd0bdf..ed96e7f212 100644
--- a/yarn.lock
+++ b/yarn.lock
@@ -1,3 +1,6 @@
+# This file is generated by running "yarn install" inside your project.
+# Manual changes might be lost - proceed with caution!
+
 __metadata:
   version: 6
   cacheKey: 8
@@ -538,15 +541,6 @@ __metadata:
   languageName: node
   linkType: hard
 
-"@aws-sdk/chunked-blob-reader@npm:3.188.0":
-  version: 3.188.0
-  resolution: "@aws-sdk/chunked-blob-reader@npm:3.188.0"
-  dependencies:
-    tslib: ^2.3.1
-  checksum: d6becebc6d77a63dd84601806c5f04bc9d0e418368fb2d593d786738119091e4d2e40721751be66260063fe7bb1c7ee2a5e075fa731eb8307722b90f6ce809dc
-  languageName: node
-  linkType: hard
-
 "@aws-sdk/chunked-blob-reader@npm:3.295.0":
   version: 3.295.0
   resolution: "@aws-sdk/chunked-blob-reader@npm:3.295.0"
@@ -556,135 +550,6 @@ __metadata:
   languageName: node
   linkType: hard
 
-"@aws-sdk/client-cognito-identity@npm:3.272.0":
-  version: 3.272.0
-  resolution: "@aws-sdk/client-cognito-identity@npm:3.272.0"
-  dependencies:
-    "@aws-crypto/sha256-browser": 3.0.0
-    "@aws-crypto/sha256-js": 3.0.0
-    "@aws-sdk/client-sts": 3.276.0
-    "@aws-sdk/config-resolver": 3.272.0
-    "@aws-sdk/credential-provider-node": 3.272.0
-    "@aws-sdk/fetch-http-handler": 3.272.0
-    "@aws-sdk/hash-node": 3.272.0
-    "@aws-sdk/invalid-dependency": 3.272.0
-    "@aws-sdk/middleware-content-length": 3.282.0
-    "@aws-sdk/middleware-endpoint": 3.282.0
-    "@aws-sdk/middleware-host-header": 3.282.0
-    "@aws-sdk/middleware-logger": 3.272.0
-    "@aws-sdk/middleware-recursion-detection": 3.282.0
-    "@aws-sdk/middleware-retry": 3.282.0
-    "@aws-sdk/middleware-serde": 3.272.0
-    "@aws-sdk/middleware-signing": 3.282.0
-    "@aws-sdk/middleware-stack": 3.272.0
-    "@aws-sdk/middleware-user-agent": 3.282.0
-    "@aws-sdk/node-config-provider": 3.272.0
-    "@aws-sdk/node-http-handler": 3.282.0
-    "@aws-sdk/protocol-http": 3.282.0
-    "@aws-sdk/smithy-client": 3.279.0
-    "@aws-sdk/types": 3.272.0
-    "@aws-sdk/url-parser": 3.272.0
-    "@aws-sdk/util-base64": 3.208.0
-    "@aws-sdk/util-body-length-browser": 3.188.0
-    "@aws-sdk/util-body-length-node": 3.208.0
-    "@aws-sdk/util-defaults-mode-browser": 3.279.0
-    "@aws-sdk/util-defaults-mode-node": 3.282.0
-    "@aws-sdk/util-endpoints": 3.272.0
-    "@aws-sdk/util-retry": 3.272.0
-    "@aws-sdk/util-user-agent-browser": 3.282.0
-    "@aws-sdk/util-user-agent-node": 3.282.0
-    "@aws-sdk/util-utf8": 3.254.0
-    tslib: ^2.3.1
-  checksum: ff79c1c727d956e03510307b001c24534d522b327871b2b0a1d39120e6d6717e17d7b9c2b7a6d28c3e5c3f41cd8ff28e5150ddd1fda9bff0c239fdfef0a78e00
-  languageName: node
-  linkType: hard
-
-"@aws-sdk/client-cognito-identity@npm:3.276.0":
-  version: 3.276.0
-  resolution: "@aws-sdk/client-cognito-identity@npm:3.276.0"
-  dependencies:
-    "@aws-crypto/sha256-browser": 3.0.0
-    "@aws-crypto/sha256-js": 3.0.0
-    "@aws-sdk/client-sts": 3.276.0
-    "@aws-sdk/config-resolver": 3.272.0
-    "@aws-sdk/credential-provider-node": 3.272.0
-    "@aws-sdk/fetch-http-handler": 3.272.0
-    "@aws-sdk/hash-node": 3.272.0
-    "@aws-sdk/invalid-dependency": 3.272.0
-    "@aws-sdk/middleware-content-length": 3.282.0
-    "@aws-sdk/middleware-endpoint": 3.282.0
-    "@aws-sdk/middleware-host-header": 3.282.0
-    "@aws-sdk/middleware-logger": 3.272.0
-    "@aws-sdk/middleware-recursion-detection": 3.282.0
-    "@aws-sdk/middleware-retry": 3.282.0
-    "@aws-sdk/middleware-serde": 3.272.0
-    "@aws-sdk/middleware-signing": 3.282.0
-    "@aws-sdk/middleware-stack": 3.272.0
-    "@aws-sdk/middleware-user-agent": 3.282.0
-    "@aws-sdk/node-config-provider": 3.272.0
-    "@aws-sdk/node-http-handler": 3.282.0
-    "@aws-sdk/protocol-http": 3.282.0
-    "@aws-sdk/smithy-client": 3.279.0
-    "@aws-sdk/types": 3.272.0
-    "@aws-sdk/url-parser": 3.272.0
-    "@aws-sdk/util-base64": 3.208.0
-    "@aws-sdk/util-body-length-browser": 3.188.0
-    "@aws-sdk/util-body-length-node": 3.208.0
-    "@aws-sdk/util-defaults-mode-browser": 3.279.0
-    "@aws-sdk/util-defaults-mode-node": 3.282.0
-    "@aws-sdk/util-endpoints": 3.272.0
-    "@aws-sdk/util-retry": 3.272.0
-    "@aws-sdk/util-user-agent-browser": 3.282.0
-    "@aws-sdk/util-user-agent-node": 3.282.0
-    "@aws-sdk/util-utf8": 3.254.0
-    tslib: ^2.3.1
-  checksum: ff79c1c727d956e03510307b001c24534d522b327871b2b0a1d39120e6d6717e17d7b9c2b7a6d28c3e5c3f41cd8ff28e5150ddd1fda9bff0c239fdfef0a78e00
-  languageName: node
-  linkType: hard
-
-"@aws-sdk/client-cognito-identity@npm:3.282.0":
-  version: 3.282.0
-  resolution: "@aws-sdk/client-cognito-identity@npm:3.282.0"
-  dependencies:
-    "@aws-crypto/sha256-browser": 3.0.0
-    "@aws-crypto/sha256-js": 3.0.0
-    "@aws-sdk/client-sts": 3.299.0
-    "@aws-sdk/config-resolver": 3.299.0
-    "@aws-sdk/credential-provider-node": 3.299.0
-    "@aws-sdk/fetch-http-handler": 3.296.0
-    "@aws-sdk/hash-node": 3.296.0
-    "@aws-sdk/invalid-dependency": 3.296.0
-    "@aws-sdk/middleware-content-length": 3.296.0
-    "@aws-sdk/middleware-endpoint": 3.299.0
-    "@aws-sdk/middleware-host-header": 3.296.0
-    "@aws-sdk/middleware-logger": 3.296.0
-    "@aws-sdk/middleware-recursion-detection": 3.296.0
-    "@aws-sdk/middleware-retry": 3.296.0
-    "@aws-sdk/middleware-serde": 3.296.0
-    "@aws-sdk/middleware-signing": 3.299.0
-    "@aws-sdk/middleware-stack": 3.296.0
-    "@aws-sdk/middleware-user-agent": 3.299.0
-    "@aws-sdk/node-config-provider": 3.296.0
-    "@aws-sdk/node-http-handler": 3.296.0
-    "@aws-sdk/protocol-http": 3.296.0
-    "@aws-sdk/smithy-client": 3.296.0
-    "@aws-sdk/types": 3.296.0
-    "@aws-sdk/url-parser": 3.296.0
-    "@aws-sdk/util-base64": 3.295.0
-    "@aws-sdk/util-body-length-browser": 3.295.0
-    "@aws-sdk/util-body-length-node": 3.295.0
-    "@aws-sdk/util-defaults-mode-browser": 3.296.0
-    "@aws-sdk/util-defaults-mode-node": 3.299.0
-    "@aws-sdk/util-endpoints": 3.296.0
-    "@aws-sdk/util-retry": 3.296.0
-    "@aws-sdk/util-user-agent-browser": 3.299.0
-    "@aws-sdk/util-user-agent-node": 3.299.0
-    "@aws-sdk/util-utf8": 3.295.0
-    tslib: ^2.5.0
-  checksum: fdcf53a12c4d5a4b71e29cac553c1aa8137fa4e5df3c23134f168618f4bd10e2480786a3de50bc9fab66aead74bd359bdbc5bf64c4d3553d71eb2488377a3f1f
-  languageName: node
-  linkType: hard
-
 "@aws-sdk/client-cognito-identity@npm:3.299.0":
   version: 3.299.0
   resolution: "@aws-sdk/client-cognito-identity@npm:3.299.0"
@@ -729,110 +594,110 @@ __metadata:
   linkType: hard
 
 "@aws-sdk/client-s3@npm:^3.208.0":
-  version: 3.282.0
-  resolution: "@aws-sdk/client-s3@npm:3.282.0"
+  version: 3.299.0
+  resolution: "@aws-sdk/client-s3@npm:3.299.0"
   dependencies:
     "@aws-crypto/sha1-browser": 3.0.0
     "@aws-crypto/sha256-browser": 3.0.0
     "@aws-crypto/sha256-js": 3.0.0
-    "@aws-sdk/client-sts": 3.282.0
-    "@aws-sdk/config-resolver": 3.282.0
-    "@aws-sdk/credential-provider-node": 3.282.0
-    "@aws-sdk/eventstream-serde-browser": 3.272.0
-    "@aws-sdk/eventstream-serde-config-resolver": 3.272.0
-    "@aws-sdk/eventstream-serde-node": 3.272.0
-    "@aws-sdk/fetch-http-handler": 3.282.0
-    "@aws-sdk/hash-blob-browser": 3.272.0
-    "@aws-sdk/hash-node": 3.272.0
-    "@aws-sdk/hash-stream-node": 3.272.0
-    "@aws-sdk/invalid-dependency": 3.272.0
-    "@aws-sdk/md5-js": 3.272.0
-    "@aws-sdk/middleware-bucket-endpoint": 3.282.0
-    "@aws-sdk/middleware-content-length": 3.282.0
-    "@aws-sdk/middleware-endpoint": 3.282.0
-    "@aws-sdk/middleware-expect-continue": 3.282.0
-    "@aws-sdk/middleware-flexible-checksums": 3.282.0
-    "@aws-sdk/middleware-host-header": 3.282.0
-    "@aws-sdk/middleware-location-constraint": 3.272.0
-    "@aws-sdk/middleware-logger": 3.272.0
-    "@aws-sdk/middleware-recursion-detection": 3.282.0
-    "@aws-sdk/middleware-retry": 3.282.0
-    "@aws-sdk/middleware-sdk-s3": 3.282.0
-    "@aws-sdk/middleware-serde": 3.272.0
-    "@aws-sdk/middleware-signing": 3.282.0
-    "@aws-sdk/middleware-ssec": 3.272.0
-    "@aws-sdk/middleware-stack": 3.272.0
-    "@aws-sdk/middleware-user-agent": 3.282.0
-    "@aws-sdk/node-config-provider": 3.272.0
-    "@aws-sdk/node-http-handler": 3.282.0
-    "@aws-sdk/protocol-http": 3.282.0
-    "@aws-sdk/signature-v4-multi-region": 3.282.0
-    "@aws-sdk/smithy-client": 3.279.0
-    "@aws-sdk/types": 3.272.0
-    "@aws-sdk/url-parser": 3.272.0
-    "@aws-sdk/util-base64": 3.208.0
-    "@aws-sdk/util-body-length-browser": 3.188.0
-    "@aws-sdk/util-body-length-node": 3.208.0
-    "@aws-sdk/util-defaults-mode-browser": 3.279.0
-    "@aws-sdk/util-defaults-mode-node": 3.282.0
-    "@aws-sdk/util-endpoints": 3.272.0
-    "@aws-sdk/util-retry": 3.272.0
-    "@aws-sdk/util-stream-browser": 3.282.0
-    "@aws-sdk/util-stream-node": 3.282.0
-    "@aws-sdk/util-user-agent-browser": 3.282.0
-    "@aws-sdk/util-user-agent-node": 3.282.0
-    "@aws-sdk/util-utf8": 3.254.0
-    "@aws-sdk/util-waiter": 3.272.0
-    "@aws-sdk/xml-builder": 3.201.0
+    "@aws-sdk/client-sts": 3.299.0
+    "@aws-sdk/config-resolver": 3.299.0
+    "@aws-sdk/credential-provider-node": 3.299.0
+    "@aws-sdk/eventstream-serde-browser": 3.296.0
+    "@aws-sdk/eventstream-serde-config-resolver": 3.296.0
+    "@aws-sdk/eventstream-serde-node": 3.299.0
+    "@aws-sdk/fetch-http-handler": 3.296.0
+    "@aws-sdk/hash-blob-browser": 3.299.0
+    "@aws-sdk/hash-node": 3.296.0
+    "@aws-sdk/hash-stream-node": 3.296.0
+    "@aws-sdk/invalid-dependency": 3.296.0
+    "@aws-sdk/md5-js": 3.296.0
+    "@aws-sdk/middleware-bucket-endpoint": 3.299.0
+    "@aws-sdk/middleware-content-length": 3.296.0
+    "@aws-sdk/middleware-endpoint": 3.299.0
+    "@aws-sdk/middleware-expect-continue": 3.296.0
+    "@aws-sdk/middleware-flexible-checksums": 3.296.0
+    "@aws-sdk/middleware-host-header": 3.296.0
+    "@aws-sdk/middleware-location-constraint": 3.296.0
+    "@aws-sdk/middleware-logger": 3.296.0
+    "@aws-sdk/middleware-recursion-detection": 3.296.0
+    "@aws-sdk/middleware-retry": 3.296.0
+    "@aws-sdk/middleware-sdk-s3": 3.296.0
+    "@aws-sdk/middleware-serde": 3.296.0
+    "@aws-sdk/middleware-signing": 3.299.0
+    "@aws-sdk/middleware-ssec": 3.296.0
+    "@aws-sdk/middleware-stack": 3.296.0
+    "@aws-sdk/middleware-user-agent": 3.299.0
+    "@aws-sdk/node-config-provider": 3.296.0
+    "@aws-sdk/node-http-handler": 3.296.0
+    "@aws-sdk/protocol-http": 3.296.0
+    "@aws-sdk/signature-v4-multi-region": 3.299.0
+    "@aws-sdk/smithy-client": 3.296.0
+    "@aws-sdk/types": 3.296.0
+    "@aws-sdk/url-parser": 3.296.0
+    "@aws-sdk/util-base64": 3.295.0
+    "@aws-sdk/util-body-length-browser": 3.295.0
+    "@aws-sdk/util-body-length-node": 3.295.0
+    "@aws-sdk/util-defaults-mode-browser": 3.296.0
+    "@aws-sdk/util-defaults-mode-node": 3.299.0
+    "@aws-sdk/util-endpoints": 3.296.0
+    "@aws-sdk/util-retry": 3.296.0
+    "@aws-sdk/util-stream-browser": 3.296.0
+    "@aws-sdk/util-stream-node": 3.296.0
+    "@aws-sdk/util-user-agent-browser": 3.299.0
+    "@aws-sdk/util-user-agent-node": 3.299.0
+    "@aws-sdk/util-utf8": 3.295.0
+    "@aws-sdk/util-waiter": 3.296.0
+    "@aws-sdk/xml-builder": 3.295.0
     fast-xml-parser: 4.1.2
-    tslib: ^2.3.1
-  checksum: 4f0a1d9ddad89eb71da6f39c210c451461d570d11bc394c6b3d7af139e3ea077bed88fee56fae8318182e7a26464d31119620f191f0d552b51125b9f6ddffe0b
+    tslib: ^2.5.0
+  checksum: 564fb486c47550e44abee25ebb98349418dc0c7d016695aeeb7fc08a0401353e0789f3191eb02825aee06e892d15c175434bf727d8e79a7af8c8deb9c08bf54d
   languageName: node
   linkType: hard
 
 "@aws-sdk/client-sqs@npm:^3.208.0":
-  version: 3.282.0
-  resolution: "@aws-sdk/client-sqs@npm:3.282.0"
+  version: 3.299.0
+  resolution: "@aws-sdk/client-sqs@npm:3.299.0"
   dependencies:
     "@aws-crypto/sha256-browser": 3.0.0
     "@aws-crypto/sha256-js": 3.0.0
-    "@aws-sdk/client-sts": 3.282.0
-    "@aws-sdk/config-resolver": 3.282.0
-    "@aws-sdk/credential-provider-node": 3.282.0
-    "@aws-sdk/fetch-http-handler": 3.282.0
-    "@aws-sdk/hash-node": 3.272.0
-    "@aws-sdk/invalid-dependency": 3.272.0
-    "@aws-sdk/md5-js": 3.272.0
-    "@aws-sdk/middleware-content-length": 3.282.0
-    "@aws-sdk/middleware-endpoint": 3.282.0
-    "@aws-sdk/middleware-host-header": 3.282.0
-    "@aws-sdk/middleware-logger": 3.272.0
-    "@aws-sdk/middleware-recursion-detection": 3.282.0
-    "@aws-sdk/middleware-retry": 3.282.0
-    "@aws-sdk/middleware-sdk-sqs": 3.272.0
-    "@aws-sdk/middleware-serde": 3.272.0
-    "@aws-sdk/middleware-signing": 3.282.0
-    "@aws-sdk/middleware-stack": 3.272.0
-    "@aws-sdk/middleware-user-agent": 3.282.0
-    "@aws-sdk/node-config-provider": 3.272.0
-    "@aws-sdk/node-http-handler": 3.282.0
-    "@aws-sdk/protocol-http": 3.282.0
-    "@aws-sdk/smithy-client": 3.279.0
-    "@aws-sdk/types": 3.272.0
-    "@aws-sdk/url-parser": 3.272.0
-    "@aws-sdk/util-base64": 3.208.0
-    "@aws-sdk/util-body-length-browser": 3.188.0
-    "@aws-sdk/util-body-length-node": 3.208.0
-    "@aws-sdk/util-defaults-mode-browser": 3.279.0
-    "@aws-sdk/util-defaults-mode-node": 3.282.0
-    "@aws-sdk/util-endpoints": 3.272.0
-    "@aws-sdk/util-retry": 3.272.0
-    "@aws-sdk/util-user-agent-browser": 3.282.0
-    "@aws-sdk/util-user-agent-node": 3.282.0
-    "@aws-sdk/util-utf8": 3.254.0
+    "@aws-sdk/client-sts": 3.299.0
+    "@aws-sdk/config-resolver": 3.299.0
+    "@aws-sdk/credential-provider-node": 3.299.0
+    "@aws-sdk/fetch-http-handler": 3.296.0
+    "@aws-sdk/hash-node": 3.296.0
+    "@aws-sdk/invalid-dependency": 3.296.0
+    "@aws-sdk/md5-js": 3.296.0
+    "@aws-sdk/middleware-content-length": 3.296.0
+    "@aws-sdk/middleware-endpoint": 3.299.0
+    "@aws-sdk/middleware-host-header": 3.296.0
+    "@aws-sdk/middleware-logger": 3.296.0
+    "@aws-sdk/middleware-recursion-detection": 3.296.0
+    "@aws-sdk/middleware-retry": 3.296.0
+    "@aws-sdk/middleware-sdk-sqs": 3.296.0
+    "@aws-sdk/middleware-serde": 3.296.0
+    "@aws-sdk/middleware-signing": 3.299.0
+    "@aws-sdk/middleware-stack": 3.296.0
+    "@aws-sdk/middleware-user-agent": 3.299.0
+    "@aws-sdk/node-config-provider": 3.296.0
+    "@aws-sdk/node-http-handler": 3.296.0
+    "@aws-sdk/protocol-http": 3.296.0
+    "@aws-sdk/smithy-client": 3.296.0
+    "@aws-sdk/types": 3.296.0
+    "@aws-sdk/url-parser": 3.296.0
+    "@aws-sdk/util-base64": 3.295.0
+    "@aws-sdk/util-body-length-browser": 3.295.0
+    "@aws-sdk/util-body-length-node": 3.295.0
+    "@aws-sdk/util-defaults-mode-browser": 3.296.0
+    "@aws-sdk/util-defaults-mode-node": 3.299.0
+    "@aws-sdk/util-endpoints": 3.296.0
+    "@aws-sdk/util-retry": 3.296.0
+    "@aws-sdk/util-user-agent-browser": 3.299.0
+    "@aws-sdk/util-user-agent-node": 3.299.0
+    "@aws-sdk/util-utf8": 3.295.0
     fast-xml-parser: 4.1.2
-    tslib: ^2.3.1
-  checksum: d3a2a2abb27313666aa8c9842c91a098b2570878a9853d59bf07d480669723d77b74ad2ca8e5297dc593d8e76578c78c2634f81e4eed84b84b020b06af04c423
+    tslib: ^2.5.0
+  checksum: a9e40735cfbef7beea646aa1047b0e629006b882b42bea61b129df415521ae5cb2e93c823d0117fb0deb38f43d7c239d4147e9268f3b78f7fd74c33634f8e7cf
   languageName: node
   linkType: hard
 
@@ -916,50 +781,6 @@ __metadata:
   languageName: node
   linkType: hard
 
-"@aws-sdk/client-sts@npm:3.282.0, @aws-sdk/client-sts@npm:^3.208.0":
-  version: 3.282.0
-  resolution: "@aws-sdk/client-sts@npm:3.282.0"
-  dependencies:
-    "@aws-crypto/sha256-browser": 3.0.0
-    "@aws-crypto/sha256-js": 3.0.0
-    "@aws-sdk/config-resolver": 3.299.0
-    "@aws-sdk/credential-provider-node": 3.299.0
-    "@aws-sdk/fetch-http-handler": 3.296.0
-    "@aws-sdk/hash-node": 3.296.0
-    "@aws-sdk/invalid-dependency": 3.296.0
-    "@aws-sdk/middleware-content-length": 3.296.0
-    "@aws-sdk/middleware-endpoint": 3.299.0
-    "@aws-sdk/middleware-host-header": 3.296.0
-    "@aws-sdk/middleware-logger": 3.296.0
-    "@aws-sdk/middleware-recursion-detection": 3.296.0
-    "@aws-sdk/middleware-retry": 3.296.0
-    "@aws-sdk/middleware-sdk-sts": 3.299.0
-    "@aws-sdk/middleware-serde": 3.296.0
-    "@aws-sdk/middleware-signing": 3.299.0
-    "@aws-sdk/middleware-stack": 3.296.0
-    "@aws-sdk/middleware-user-agent": 3.299.0
-    "@aws-sdk/node-config-provider": 3.296.0
-    "@aws-sdk/node-http-handler": 3.296.0
-    "@aws-sdk/protocol-http": 3.296.0
-    "@aws-sdk/smithy-client": 3.296.0
-    "@aws-sdk/types": 3.296.0
-    "@aws-sdk/url-parser": 3.296.0
-    "@aws-sdk/util-base64": 3.295.0
-    "@aws-sdk/util-body-length-browser": 3.295.0
-    "@aws-sdk/util-body-length-node": 3.295.0
-    "@aws-sdk/util-defaults-mode-browser": 3.296.0
-    "@aws-sdk/util-defaults-mode-node": 3.299.0
-    "@aws-sdk/util-endpoints": 3.296.0
-    "@aws-sdk/util-retry": 3.296.0
-    "@aws-sdk/util-user-agent-browser": 3.299.0
-    "@aws-sdk/util-user-agent-node": 3.299.0
-    "@aws-sdk/util-utf8": 3.295.0
-    fast-xml-parser: 4.1.2
-    tslib: ^2.5.0
-  checksum: 4a9160e0e79a3f5d39646d56dbd9a0cb52063164df42e88640019ca74e88e49f7c36ddb98beae537051eb0798d912e283262657bdf420c6640ed04783f2d3d72
-  languageName: node
-  linkType: hard
-
 "@aws-sdk/client-sts@npm:3.299.0, @aws-sdk/client-sts@npm:^3.208.0":
   version: 3.299.0
   resolution: "@aws-sdk/client-sts@npm:3.299.0"
@@ -1004,18 +825,6 @@ __metadata:
   languageName: node
   linkType: hard
 
-"@aws-sdk/config-resolver@npm:3.282.0":
-  version: 3.282.0
-  resolution: "@aws-sdk/config-resolver@npm:3.282.0"
-  dependencies:
-    "@aws-sdk/types": 3.296.0
-    "@aws-sdk/util-config-provider": 3.295.0
-    "@aws-sdk/util-middleware": 3.296.0
-    tslib: ^2.5.0
-  checksum: 2fc2bd424a3b24cabf1df549b6102a47657ddf77f6d81cf2d477fd7eec407071febc5ec5e21384903104526b753c71777106c24dfdfd055e2b8cd810d7d50730
-  languageName: node
-  linkType: hard
-
 "@aws-sdk/config-resolver@npm:3.299.0":
   version: 3.299.0
   resolution: "@aws-sdk/config-resolver@npm:3.299.0"
@@ -1028,18 +837,6 @@ __metadata:
   languageName: node
   linkType: hard
 
-"@aws-sdk/credential-provider-cognito-identity@npm:3.282.0":
-  version: 3.282.0
-  resolution: "@aws-sdk/credential-provider-cognito-identity@npm:3.282.0"
-  dependencies:
-    "@aws-sdk/client-cognito-identity": 3.299.0
-    "@aws-sdk/property-provider": 3.296.0
-    "@aws-sdk/types": 3.296.0
-    tslib: ^2.5.0
-  checksum: 03a1719599fa72cd42677a6b59cdb22285b0b27353489c9b04ddafc0a61d3cdd2206f90e456c2e162fb8b85f7d8214f25b774368624fa087dcd42f6ef187c8e6
-  languageName: node
-  linkType: hard
-
 "@aws-sdk/credential-provider-cognito-identity@npm:3.299.0":
   version: 3.299.0
   resolution: "@aws-sdk/credential-provider-cognito-identity@npm:3.299.0"
@@ -1149,25 +946,24 @@ __metadata:
   linkType: hard
 
 "@aws-sdk/credential-providers@npm:^3.208.0":
-  version: 3.282.0
-  resolution: "@aws-sdk/credential-providers@npm:3.282.0"
+  version: 3.299.0
+  resolution: "@aws-sdk/credential-providers@npm:3.299.0"
   dependencies:
-    "@aws-sdk/client-cognito-identity": 3.282.0
-    "@aws-sdk/client-sso": 3.282.0
-    "@aws-sdk/client-sts": 3.282.0
-    "@aws-sdk/credential-provider-cognito-identity": 3.282.0
-    "@aws-sdk/credential-provider-env": 3.272.0
-    "@aws-sdk/credential-provider-imds": 3.272.0
-    "@aws-sdk/credential-provider-ini": 3.282.0
-    "@aws-sdk/credential-provider-node": 3.282.0
-    "@aws-sdk/credential-provider-process": 3.272.0
-    "@aws-sdk/credential-provider-sso": 3.282.0
-    "@aws-sdk/credential-provider-web-identity": 3.272.0
-    "@aws-sdk/property-provider": 3.272.0
-    "@aws-sdk/shared-ini-file-loader": 3.272.0
-    "@aws-sdk/types": 3.272.0
-    tslib: ^2.3.1
-  checksum: ec707176eba558fc5bfc45b2917d624a83995c75bfc38a121d3a3fe6c0be541c25815d4892fc33fd0f1de5f892232014724b0d5c62c19a2d6d3f839258b25840
+    "@aws-sdk/client-cognito-identity": 3.299.0
+    "@aws-sdk/client-sso": 3.299.0
+    "@aws-sdk/client-sts": 3.299.0
+    "@aws-sdk/credential-provider-cognito-identity": 3.299.0
+    "@aws-sdk/credential-provider-env": 3.296.0
+    "@aws-sdk/credential-provider-imds": 3.296.0
+    "@aws-sdk/credential-provider-ini": 3.299.0
+    "@aws-sdk/credential-provider-node": 3.299.0
+    "@aws-sdk/credential-provider-process": 3.296.0
+    "@aws-sdk/credential-provider-sso": 3.299.0
+    "@aws-sdk/credential-provider-web-identity": 3.296.0
+    "@aws-sdk/property-provider": 3.296.0
+    "@aws-sdk/types": 3.296.0
+    tslib: ^2.5.0
+  checksum: 0c1f49d6e057925f13a1a7028bb4fee124a1ec08d16fe5616aa7272007d8a9e70cd292726628a95d17a7d7099c91b88d94712faa2751da34bebee574f6e2ee4d
   languageName: node
   linkType: hard
 
@@ -1293,8 +1089,8 @@ __metadata:
   linkType: hard
 
 "@aws-sdk/lib-storage@npm:^3.208.0":
-  version: 3.282.0
-  resolution: "@aws-sdk/lib-storage@npm:3.282.0"
+  version: 3.299.0
+  resolution: "@aws-sdk/lib-storage@npm:3.299.0"
   dependencies:
     "@aws-sdk/middleware-endpoint": 3.299.0
     "@aws-sdk/smithy-client": 3.296.0
@@ -1305,7 +1101,7 @@ __metadata:
   peerDependencies:
     "@aws-sdk/abort-controller": ^3.0.0
     "@aws-sdk/client-s3": ^3.0.0
-  checksum: 14f1f21a653d239721ca488b6d7951511576a2e2652d240f3561ac0255cd4af321bc41531c15c3c6fae4095da062f5e841c6c9b58afd80be9bf105b63a256f72
+  checksum: bbf180386c03ac4fb78c65c7b476dbb6bb5c81a4d8013e8c216710b6654642e89d4cd6dc8fe3383b42c285c098ca8f325199b58efdc13b5278ed6ce011b28331
   languageName: node
   linkType: hard
 
@@ -15054,13 +14850,6 @@ __metadata:
   languageName: node
   linkType: hard
 
-"@tanstack/query-core@npm:4.24.10":
-  version: 4.24.10
-  resolution: "@tanstack/query-core@npm:4.24.10"
-  checksum: 8268b9dca4a2ed39f8575976d8a3e2f839bb6f4fb821dc00ba8e2aeffffe2f73e23344bcc24b9cb6dae9dbfe3ba2b14c76a1e0a38b4064c83beb9aa607fd94bc
-  languageName: node
-  linkType: hard
-
 "@tanstack/query-core@npm:4.27.0":
   version: 4.27.0
   resolution: "@tanstack/query-core@npm:4.27.0"
@@ -15069,10 +14858,10 @@ __metadata:
   linkType: hard
 
 "@tanstack/react-query@npm:^4.1.3":
-  version: 4.24.10
-  resolution: "@tanstack/react-query@npm:4.24.10"
+  version: 4.28.0
+  resolution: "@tanstack/react-query@npm:4.28.0"
   dependencies:
-    "@tanstack/query-core": 4.24.10
+    "@tanstack/query-core": 4.27.0
     use-sync-external-store: ^1.2.0
   peerDependencies:
     react: ^16.8.0 || ^17.0.0 || ^18.0.0
@@ -15083,7 +14872,7 @@ __metadata:
       optional: true
     react-native:
       optional: true
-  checksum: 576a2c73e98cf6a3c9584283989383d5ac63b01efe546cc7580ec7b1edf0c0cb8958a3071778cb0af908f5269d45c7516fa388e5f856e37f5b2d3c6110974cbe
+  checksum: 7baa70d22b55cfa22f8a1d92ba9f8379c5436ee81fce3f0e7df4a8c29bb26bfef4a83759cf10f752b40ae2940099fcce88ce91a773240f4999ae91136980c6e3
   languageName: node
   linkType: hard
 
@@ -15806,17 +15595,6 @@ __metadata:
   languageName: node
   linkType: hard
 
-"@types/express-serve-static-core@npm:*, @types/express-serve-static-core@npm:^4.17.30, @types/express-serve-static-core@npm:^4.17.31, @types/express-serve-static-core@npm:^4.17.5":
-  version: 4.17.33
-  resolution: "@types/express-serve-static-core@npm:4.17.33"
-  dependencies:
-    "@types/node": "*"
-    "@types/qs": "*"
-    "@types/range-parser": "*"
-  checksum: dce580d16b85f207445af9d4053d66942b27d0c72e86153089fa00feee3e96ae336b7bedb31ed4eea9e553c99d6dd356ed6e0928f135375d9f862a1a8015adf2
-  languageName: node
-  linkType: hard
-
 "@types/express-serve-static-core@npm:*, @types/express-serve-static-core@npm:^4.17.30, @types/express-serve-static-core@npm:^4.17.33, @types/express-serve-static-core@npm:^4.17.5":
   version: 4.17.33
   resolution: "@types/express-serve-static-core@npm:4.17.33"
@@ -15848,14 +15626,14 @@ __metadata:
   linkType: hard
 
 "@types/express@npm:*, @types/express@npm:^4.17.13, @types/express@npm:^4.17.6":
-  version: 4.17.16
-  resolution: "@types/express@npm:4.17.16"
+  version: 4.17.17
+  resolution: "@types/express@npm:4.17.17"
   dependencies:
     "@types/body-parser": "*"
-    "@types/express-serve-static-core": ^4.17.31
+    "@types/express-serve-static-core": ^4.17.33
     "@types/qs": "*"
     "@types/serve-static": "*"
-  checksum: 43f3ed2cea6e5e83c7c1098c5152f644e975fd764443717ff9c812a1518416a9e7e9f824ffe852c118888cbfb994ed023cad08331f49b19ced469bb185cdd5cd
+  checksum: 0196dacc275ac3ce89d7364885cb08e7fb61f53ca101f65886dbf1daf9b7eb05c0943e2e4bbd01b0cc5e50f37e0eea7e4cbe97d0304094411ac73e1b7998f4da
   languageName: node
   linkType: hard
 
@@ -17931,31 +17709,7 @@ __metadata:
   languageName: node
   linkType: hard
 
-"ajv@npm:^8.0.0, ajv@npm:^8.1.0, ajv@npm:^8.10.0, ajv@npm:^8.11.0, ajv@npm:^8.12.0, ajv@npm:^8.3.0, ajv@npm:^8.4.0, ajv@npm:^8.8.0":
-  version: 8.12.0
-  resolution: "ajv@npm:8.12.0"
-  dependencies:
-    fast-deep-equal: ^3.1.1
-    json-schema-traverse: ^1.0.0
-    require-from-string: ^2.0.2
-    uri-js: ^4.2.2
-  checksum: 4dc13714e316e67537c8b31bc063f99a1d9d9a497eb4bbd55191ac0dcd5e4985bbb71570352ad6f1e76684fb6d790928f96ba3b2d4fd6e10024be9612fe3f001
-  languageName: node
-  linkType: hard
-
-"ajv@npm:^8.0.0, ajv@npm:^8.10.0, ajv@npm:^8.12.0, ajv@npm:^8.6.3, ajv@npm:^8.8.0":
-  version: 8.12.0
-  resolution: "ajv@npm:8.12.0"
-  dependencies:
-    fast-deep-equal: ^3.1.1
-    json-schema-traverse: ^1.0.0
-    require-from-string: ^2.0.2
-    uri-js: ^4.2.2
-  checksum: 4dc13714e316e67537c8b31bc063f99a1d9d9a497eb4bbd55191ac0dcd5e4985bbb71570352ad6f1e76684fb6d790928f96ba3b2d4fd6e10024be9612fe3f001
-  languageName: node
-  linkType: hard
-
-"ajv@npm:^8.0.0, ajv@npm:^8.10.0, ajv@npm:^8.12.0, ajv@npm:^8.8.0":
+"ajv@npm:^8.0.0, ajv@npm:^8.10.0, ajv@npm:^8.11.0, ajv@npm:^8.12.0, ajv@npm:^8.6.3, ajv@npm:^8.8.0":
   version: 8.12.0
   resolution: "ajv@npm:8.12.0"
   dependencies:
@@ -38865,13 +38619,6 @@ __metadata:
   languageName: node
   linkType: hard
 
-"ts-toolbelt@npm:^9.6.0":
-  version: 9.6.0
-  resolution: "ts-toolbelt@npm:9.6.0"
-  checksum: 9f35fd95d895a5d32ea9fd2e532a695b0bae6cbff6832b77292efa188a0ed1ed6e54f63f74a8920390f3d909a7a3adb20a144686372a8e78b420246a9bd3d58a
-  languageName: node
-  linkType: hard
-
 "tsconfig-paths@npm:^3.14.1":
   version: 3.14.1
   resolution: "tsconfig-paths@npm:3.14.1"