feat(repo-tools): add a new command that provides dynamic test-driven OpenAPI schema feedback.

Signed-off-by: Aramis Sennyey <aramiss@spotify.com>
Signed-off-by: Aramis <sennyeyaramis@gmail.com>

packages/backend-openapi-utils/README.md

@@ -65,7 +65,7 @@ export function createRouter() {
 
 ### Why am I getting `unknown` as the type for a response?
 
-This can happen when you have a `charset` defined in your `response.content` section. Something like `response.content[    'application/json; charset=utf-8:']` will cause this issue.
+This can happen when you have a `charset` defined in your `response.content` section. Something like `response.content['application/json; charset=utf-8:']` will cause this issue.
 
 ## INTERNAL
 

packages/backend-openapi-utils/api-report.md

@@ -5,6 +5,7 @@
 ```ts
 import type { ContentObject } from 'openapi3-ts';
 import type core from 'express-serve-static-core';
+import { Express as Express_2 } from 'express';
 import { FromSchema } from 'json-schema-to-ts';
 import { JSONSchema7 } from 'json-schema-to-ts';
 import { middleware } from 'express-openapi-validator';
@@ -16,6 +17,7 @@ import { RequestHandler } from 'express';
 import type { ResponseObject } from 'openapi3-ts';
 import { Router } from 'express';
 import type { SchemaObject } from 'openapi3-ts';
+import { Server } from 'http';
 
 // @public
 export interface ApiRouter<Doc extends RequiredDoc> extends Router {
@@ -708,4 +710,7 @@ type UnknownIfNever<P> = [P] extends [never] ? unknown : P;
 
 // @public
 type ValueOf<T> = T[keyof T];
+
+// @public
+export const wrapInOpenApiTestServer: (app: Express_2) => Server | Express_2;
 ```

packages/backend-openapi-utils/src/index.ts

@@ -32,3 +32,4 @@ export type {
 } from './utility';
 export type { ApiRouter } from './router';
 export { createValidatedOpenApiRouter } from './stub';
+export { wrapInOpenApiTestServer } from './testUtils';

packages/backend-openapi-utils/src/stub.test.ts

@@ -27,7 +27,6 @@ describe('createRouter', () => {
     status: 'available',
     photoUrls: [],
   };
-
   it('does NOT override originalUrl and basePath after execution', async () => {
     expect.assertions(2);
     const router = createValidatedOpenApiRouter(singlePathSpec);

packages/backend-openapi-utils/src/testUtils.ts

@@ -0,0 +1,36 @@
+/*
+ * 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 { Server } from 'http';
+
+/**
+ * !!! THIS CURRENTLY ONLY SUPPORTS SUPERTEST !!!
+ * Running against supertest, we need some way to hit the optic proxy. This ensures that
+ *  that happens at runtime when in the context of a `yarn optic capture` command.
+ * @param app - Express router that would be passed to supertest's `request`.
+ * @returns A wrapper around the express router (or the router untouched) that still works with supertest.
+ * @public
+ */
+export const wrapInOpenApiTestServer = (app: Express): Server | Express => {
+  if (process.env.OPTIC_PROXY) {
+    const server = app.listen(+process.env.PORT!);
+    return {
+      ...server,
+      address: () => new URL(process.env.OPTIC_PROXY!),
+    } as any;
+  }
+  return app;
+};