Merge branch 'master' into api-docs-new-backend

Signed-off-by: Patrik Oldsberg <poldsberg@gmail.com>

packages/backend-openapi-utils/CHANGELOG.md

@@ -1,5 +1,29 @@
 # @backstage/backend-openapi-utils
 
+## 0.0.5
+
+### Patch Changes
+
+- 7c83975531: Adds new public utility types for common OpenAPI values, like request and response shapes and parameters available on an endpoint.
+
+  **deprecated** `internal` namespace
+  The internal namespace will continue to be exported but now uses OpenAPI format for path parameters. You should use the new utility types.
+
+- Updated dependencies
+  - @backstage/errors@1.2.3
+
+## 0.0.5-next.0
+
+### Patch Changes
+
+- 7c83975531: Adds new public utility types for common OpenAPI values, like request and response shapes and parameters available on an endpoint.
+
+  **deprecated** `internal` namespace
+  The internal namespace will continue to be exported but now uses OpenAPI format for path parameters. You should use the new utility types.
+
+- Updated dependencies
+  - @backstage/errors@1.2.3-next.0
+
 ## 0.0.4
 
 ### Patch Changes

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 {
@@ -711,4 +713,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/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@backstage/backend-openapi-utils",
   "description": "OpenAPI typescript support.",
-  "version": "0.0.4",
+  "version": "0.0.5",
   "main": "src/index.ts",
   "types": "src/index.ts",
   "license": "Apache-2.0",

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

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

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;
+};