From 45454f217866308a2aae6e36fde8cfb79e48312c Mon Sep 17 00:00:00 2001
From: Aramis Sennyey <aramiss@spotify.com>
Date: Mon, 18 Sep 2023 18:34:14 -0400
Subject: [PATCH 1/4] fix: clean up the exported types

Signed-off-by: Aramis Sennyey <aramiss@spotify.com>
---
 packages/backend-openapi-utils/README.md      |   6 +
 packages/backend-openapi-utils/api-report.md  | 125 ++++++++++--------
 .../backend-openapi-utils/src/stub.test.ts    |  14 +-
 .../backend-openapi-utils/src/types/common.ts |  45 ++++---
 .../src/types/express.ts                      |  41 ++++--
 .../backend-openapi-utils/src/types/params.ts |  23 ++--
 .../src/types/requests.ts                     |  14 +-
 .../src/types/responses.ts                    |  11 +-
 packages/backend-openapi-utils/src/utility.ts |  81 ++++++++++++
 .../request/parseQueryEntitiesParams.ts       |   4 +-
 10 files changed, 250 insertions(+), 114 deletions(-)
 create mode 100644 packages/backend-openapi-utils/src/utility.ts

diff --git a/packages/backend-openapi-utils/README.md b/packages/backend-openapi-utils/README.md
index 1efab0e85b..ca3f03fcc1 100644
--- a/packages/backend-openapi-utils/README.md
+++ b/packages/backend-openapi-utils/README.md
@@ -61,6 +61,12 @@ export function createRouter() {
 }
 ```
 
+## FAQs
+
+### 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.
+
 ## INTERNAL
 
 ### Limitations
diff --git a/packages/backend-openapi-utils/api-report.md b/packages/backend-openapi-utils/api-report.md
index 08ffa23a30..26215ad2a5 100644
--- a/packages/backend-openapi-utils/api-report.md
+++ b/packages/backend-openapi-utils/api-report.md
@@ -77,9 +77,9 @@ interface CookieObject extends ParameterObject {
 // @public (undocumented)
 type CookieSchema<
   Doc extends RequiredDoc,
-  Path extends PathTemplate<Extract<keyof Doc['paths'], string>>,
+  Path extends DocPath<Doc>,
   Method extends DocPathMethod<Doc, Path>,
-> = ParametersSchema<Doc, DocPath<Doc, Path>, Method, ImmutableCookieObject>;
+> = ParametersSchema<Doc, Path, Method, ImmutableCookieObject>;
 
 // @public
 export function createValidatedOpenApiRouter<T extends RequiredDoc>(
@@ -99,16 +99,16 @@ type DiscriminateUnion<T, K extends keyof T, V extends T[K]> = Extract<
 // @public (undocumented)
 type DocOperation<
   Doc extends RequiredDoc,
-  Path extends keyof Doc['paths'],
+  Path extends DocPath<Doc>,
   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'],
+  Path extends DocPath<Doc>,
+  Method extends DocPathMethod<Doc, Path>,
+  Parameter extends keyof DocOperation<Doc, Path, Method>['parameters'],
 > = DocOperation<
   Doc,
   Path,
@@ -142,32 +142,28 @@ type DocParameters<
 };
 
 // @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;
-}>;
+type DocPath<Doc extends PathDoc> = Extract<keyof Doc['paths'], string>;
 
 // @public (undocumented)
 type DocPathMethod<
   Doc extends Pick<RequiredDoc, 'paths'>,
-  Path extends DocPathTemplate<Doc>,
-> = keyof Doc['paths'][DocPath<Doc, Path>];
+  Path extends DocPath<Doc>,
+> = keyof Doc['paths'][Path];
 
 // @public (undocumented)
-type DocPathTemplate<Doc extends PathDoc> = PathTemplate<
-  Extract<keyof Doc['paths'], string>
->;
+type DocPathTemplate<Doc extends PathDoc> = PathTemplate<DocPath<Doc>>;
+
+// @public (undocumented)
+type DocPathTemplateMethod<
+  Doc extends Pick<RequiredDoc, 'paths'>,
+  Path extends DocPathTemplate<Doc>,
+> = keyof Doc['paths'][TemplateToDocPath<Doc, Path>];
 
 // @public
 type DocRequestHandler<
   Doc extends RequiredDoc,
-  Path extends DocPathTemplate<Doc>,
-  Method extends keyof Doc['paths'][Path],
+  Path extends DocPath<Doc>,
+  Method extends DocPathMethod<Doc, Path>,
 > = core.RequestHandler<
   PathSchema<Doc, Path, Method>,
   ResponseBodyToJsonSchema<Doc, Path, Method>,
@@ -179,8 +175,8 @@ type DocRequestHandler<
 // @public
 type DocRequestHandlerParams<
   Doc extends RequiredDoc,
-  Path extends DocPathTemplate<Doc>,
-  Method extends keyof Doc['paths'][Path],
+  Path extends DocPath<Doc>,
+  Method extends DocPathMethod<Doc, Path>,
 > = core.RequestHandlerParams<
   PathSchema<Doc, Path, Method>,
   ResponseBodyToJsonSchema<Doc, Path, Method>,
@@ -204,14 +200,30 @@ interface DocRequestMatcher<
     | 'head',
 > {
   // (undocumented)
-  <Path extends MethodAwareDocPath<Doc, DocPathTemplate<Doc>, Method>>(
+  <
+    Path extends MethodAwareDocPath<
+      Doc,
+      PathTemplate<Extract<keyof Doc['paths'], string>>,
+      Method
+    >,
+  >(
     path: Path,
-    ...handlers: Array<DocRequestHandler<Doc, Path, Method>>
+    ...handlers: Array<
+      DocRequestHandler<Doc, TemplateToDocPath<Doc, Path>, Method>
+    >
   ): T;
   // (undocumented)
-  <Path extends MethodAwareDocPath<Doc, DocPathTemplate<Doc>, Method>>(
+  <
+    Path extends MethodAwareDocPath<
+      Doc,
+      PathTemplate<Extract<keyof Doc['paths'], string>>,
+      Method
+    >,
+  >(
     path: Path,
-    ...handlers: Array<DocRequestHandlerParams<Doc, Path, Method>>
+    ...handlers: Array<
+      DocRequestHandlerParams<Doc, TemplateToDocPath<Doc, Path>, Method>
+    >
   ): T;
 }
 
@@ -240,9 +252,9 @@ interface HeaderObject extends ParameterObject {
 // @public (undocumented)
 type HeaderSchema<
   Doc extends RequiredDoc,
-  Path extends PathTemplate<Extract<keyof Doc['paths'], string>>,
+  Path extends DocPath<Doc>,
   Method extends DocPathMethod<Doc, Path>,
-> = ParametersSchema<Doc, DocPath<Doc, Path>, Method, ImmutableHeaderObject>;
+> = ParametersSchema<Doc, Path, Method, ImmutableHeaderObject>;
 
 // @public
 type Immutable<T> = T extends
@@ -304,10 +316,12 @@ declare namespace internal {
     RequiredDoc,
     PathDoc,
     ValueOf,
-    PathTemplate,
     DocPath,
+    PathTemplate,
+    TemplateToDocPath,
     DocPathTemplate,
     DocPathMethod,
+    DocPathTemplateMethod,
     MethodAwareDocPath,
     DocOperation,
     ComponentTypes,
@@ -394,14 +408,11 @@ type MapToSchema<
 // @public (undocumented)
 type MethodAwareDocPath<
   Doc extends PathDoc,
-  Path extends PathTemplate<Extract<keyof Doc['paths'], string>>,
-  Method extends keyof Doc['paths'][Path],
+  Path extends DocPathTemplate<Doc>,
+  Method extends DocPathTemplateMethod<Doc, Path>,
 > = ValueOf<{
-  [Template in Extract<
-    keyof Doc['paths'],
-    string
-  >]: Path extends PathTemplate<Template>
-    ? Method extends DocPathMethod<Doc, Path>
+  [Template in DocPath<Doc>]: Path extends PathTemplate<Template>
+    ? Method extends DocPathTemplateMethod<Doc, Path>
       ? PathTemplate<Template>
       : never
     : never;
@@ -468,9 +479,9 @@ interface PathObject extends ParameterObject {
 // @public (undocumented)
 type PathSchema<
   Doc extends RequiredDoc,
-  Path extends PathTemplate<Extract<keyof Doc['paths'], string>>,
+  Path extends DocPath<Doc>,
   Method extends DocPathMethod<Doc, Path>,
-> = ParametersSchema<Doc, DocPath<Doc, Path>, Method, ImmutablePathObject>;
+> = ParametersSchema<Doc, Path, Method, ImmutablePathObject>;
 
 // @public
 type PathTemplate<Path extends string> =
@@ -510,9 +521,9 @@ interface QueryObject extends ParameterObject {
 // @public (undocumented)
 type QuerySchema<
   Doc extends RequiredDoc,
-  Path extends PathTemplate<Extract<keyof Doc['paths'], string>>,
+  Path extends DocPath<Doc>,
   Method extends DocPathMethod<Doc, Path>,
-> = ParametersSchema<Doc, DocPath<Doc, Path>, Method, ImmutableQueryObject>;
+> = ParametersSchema<Doc, Path, Method, ImmutableQueryObject>;
 
 // @public (undocumented)
 type RequestBody<
@@ -536,20 +547,16 @@ type RequestBody<
 // @public (undocumented)
 type RequestBodySchema<
   Doc extends RequiredDoc,
-  Path extends DocPathTemplate<Doc>,
+  Path extends DocPath<Doc>,
   Method extends DocPathMethod<Doc, Path>,
-> = RequestBody<
-  Doc,
-  DocPath<Doc, Path>,
-  Method
-> extends ImmutableRequestBodyObject
-  ? ObjectWithContentSchema<Doc, RequestBody<Doc, DocPath<Doc, Path>, Method>>
+> = RequestBody<Doc, Path, Method> extends ImmutableRequestBodyObject
+  ? ObjectWithContentSchema<Doc, RequestBody<Doc, Path, Method>>
   : never;
 
 // @public
 type RequestBodyToJsonSchema<
   Doc extends RequiredDoc,
-  Path extends PathTemplate<Extract<keyof Doc['paths'], string>>,
+  Path extends DocPath<Doc>,
   Method extends DocPathMethod<Doc, Path>,
 > = ToTypeSafe<RequestBodySchema<Doc, Path, Method>>;
 
@@ -568,8 +575,8 @@ type RequiredMap<
 // @public (undocumented)
 type Response_2<
   Doc extends RequiredDoc,
-  Path extends keyof Doc['paths'],
-  Method extends keyof Doc['paths'][Path],
+  Path extends DocPath<Doc>,
+  Method extends DocPathMethod<Doc, Path>,
   StatusCode extends keyof DocOperation<Doc, Path, Method>['responses'],
 > = DocOperation<
   Doc,
@@ -588,14 +595,14 @@ type Response_2<
 // @public
 type ResponseBodyToJsonSchema<
   Doc extends RequiredDoc,
-  Path extends PathTemplate<Extract<keyof Doc['paths'], string>>,
+  Path extends DocPath<Doc>,
   Method extends DocPathMethod<Doc, Path>,
 > = ToTypeSafe<ValueOf<ResponseSchemas<Doc, Path, Method>>>;
 
 // @public (undocumented)
 type ResponseSchemas<
   Doc extends RequiredDoc,
-  Path extends DocPathTemplate<Doc>,
+  Path extends DocPath<Doc>,
   Method extends DocPathMethod<Doc, Path>,
 > = {
   [StatusCode in keyof DocOperation<
@@ -625,6 +632,16 @@ type SchemaRef<Doc extends RequiredDoc, Schema> = Schema extends {
       [Key in keyof Schema]: SchemaRef<Doc, Schema[Key]>;
     };
 
+// @public
+type TemplateToDocPath<
+  Doc extends PathDoc,
+  Path extends DocPathTemplate<Doc>,
+> = ValueOf<{
+  [Template in DocPath<Doc>]: Path extends PathTemplate<Template>
+    ? Template
+    : never;
+}>;
+
 // @public (undocumented)
 type ToTypeSafe<T> = UnknownIfNever<ConvertAll<TuplifyUnion<T>>[number]>;
 
diff --git a/packages/backend-openapi-utils/src/stub.test.ts b/packages/backend-openapi-utils/src/stub.test.ts
index 678445c818..c9ec955e95 100644
--- a/packages/backend-openapi-utils/src/stub.test.ts
+++ b/packages/backend-openapi-utils/src/stub.test.ts
@@ -18,15 +18,23 @@ import { createValidatedOpenApiRouter } from './stub';
 import express from 'express';
 import request from 'supertest';
 import singlePathSpec from './___fixtures__/single-path';
+import { Response } from './utility';
 
 describe('createRouter', () => {
+  const pet: Response<typeof singlePathSpec, '/pet/:petId', 'get'> = {
+    id: 1,
+    name: 'rover',
+    status: 'available',
+    photoUrls: [],
+  };
+
   it('does NOT override originalUrl and basePath after execution', async () => {
     expect.assertions(2);
     const router = createValidatedOpenApiRouter(singlePathSpec);
     router.get('/pet/:petId', (req, res) => {
       expect(req.baseUrl).toBe('/pet-store');
       expect(req.originalUrl).toBe(`/pet-store/pet/${req.params.petId}`);
-      res.send('');
+      res.status(400).send();
     });
 
     const appRouter = express();
@@ -41,7 +49,7 @@ describe('createRouter', () => {
     const routerGetFn = jest.fn();
     router.get('/pet/:petId', (_, res) => {
       routerGetFn();
-      res.send('');
+      res.json(pet);
     });
 
     const apiRouter = express.Router();
@@ -58,7 +66,7 @@ describe('createRouter', () => {
     const router = createValidatedOpenApiRouter(singlePathSpec);
     router.get('/pet/:petId', (req, res) => {
       expect(typeof req.params.petId).toBe('integer');
-      res.send('');
+      res.json(pet);
     });
 
     const apiRouter = express.Router();
diff --git a/packages/backend-openapi-utils/src/types/common.ts b/packages/backend-openapi-utils/src/types/common.ts
index 5568ed795c..c3c7284369 100644
--- a/packages/backend-openapi-utils/src/types/common.ts
+++ b/packages/backend-openapi-utils/src/types/common.ts
@@ -42,6 +42,13 @@ export type PathDoc = Pick<ImmutableOpenAPIObject, 'paths'>;
  */
 export type ValueOf<T> = T[keyof T];
 
+/**
+ * All paths for a given doc,
+ * @example `/pet/{petId}` | `/pet`
+ * @public
+ */
+export type DocPath<Doc extends PathDoc> = Extract<keyof Doc['paths'], string>;
+
 /**
  * Validate a string against OpenAPI path template, {@link https://spec.openapis.org/oas/v3.1.0#path-templating-matching}.
  *
@@ -74,44 +81,46 @@ export type PathTemplate<Path extends string> =
  *
  * @public
  */
-export type DocPath<
+export type TemplateToDocPath<
   Doc extends PathDoc,
-  Path extends PathTemplate<Extract<keyof Doc['paths'], string>>,
+  Path extends DocPathTemplate<Doc>,
 > = ValueOf<{
-  [Template in Extract<
-    keyof Doc['paths'],
-    string
-  >]: Path extends PathTemplate<Template> ? Template : never;
+  [Template in DocPath<Doc>]: Path extends PathTemplate<Template>
+    ? Template
+    : never;
 }>;
 
 /**
  * @public
  */
-export type DocPathTemplate<Doc extends PathDoc> = PathTemplate<
-  Extract<keyof Doc['paths'], string>
->;
+export type DocPathTemplate<Doc extends PathDoc> = PathTemplate<DocPath<Doc>>;
 
 /**
  * @public
  */
 export type DocPathMethod<
+  Doc extends Pick<RequiredDoc, 'paths'>,
+  Path extends DocPath<Doc>,
+> = keyof Doc['paths'][Path];
+
+/**
+ * @public
+ */
+export type DocPathTemplateMethod<
   Doc extends Pick<RequiredDoc, 'paths'>,
   Path extends DocPathTemplate<Doc>,
-> = keyof Doc['paths'][DocPath<Doc, Path>];
+> = keyof Doc['paths'][TemplateToDocPath<Doc, Path>];
 
 /**
  * @public
  */
 export type MethodAwareDocPath<
   Doc extends PathDoc,
-  Path extends PathTemplate<Extract<keyof Doc['paths'], string>>,
-  Method extends keyof Doc['paths'][Path],
+  Path extends DocPathTemplate<Doc>,
+  Method extends DocPathTemplateMethod<Doc, Path>,
 > = ValueOf<{
-  [Template in Extract<
-    keyof Doc['paths'],
-    string
-  >]: Path extends PathTemplate<Template>
-    ? Method extends DocPathMethod<Doc, Path>
+  [Template in DocPath<Doc>]: Path extends PathTemplate<Template>
+    ? Method extends DocPathTemplateMethod<Doc, Path>
       ? PathTemplate<Template>
       : never
     : never;
@@ -122,7 +131,7 @@ export type MethodAwareDocPath<
  */
 export type DocOperation<
   Doc extends RequiredDoc,
-  Path extends keyof Doc['paths'],
+  Path extends DocPath<Doc>,
   Method extends keyof Doc['paths'][Path],
 > = Doc['paths'][Path][Method];
 
diff --git a/packages/backend-openapi-utils/src/types/express.ts b/packages/backend-openapi-utils/src/types/express.ts
index b0020dab37..127400099a 100644
--- a/packages/backend-openapi-utils/src/types/express.ts
+++ b/packages/backend-openapi-utils/src/types/express.ts
@@ -14,7 +14,14 @@
  * limitations under the License.
  */
 import type core from 'express-serve-static-core';
-import { DocPathTemplate, MethodAwareDocPath, RequiredDoc } from './common';
+import {
+  DocPath,
+  DocPathMethod,
+  MethodAwareDocPath,
+  PathTemplate,
+  RequiredDoc,
+  TemplateToDocPath,
+} from './common';
 import { PathSchema, QuerySchema } from './params';
 import { RequestBodyToJsonSchema } from './requests';
 import { ResponseBodyToJsonSchema } from './responses';
@@ -25,8 +32,8 @@ import { ResponseBodyToJsonSchema } from './responses';
  */
 export type DocRequestHandler<
   Doc extends RequiredDoc,
-  Path extends DocPathTemplate<Doc>,
-  Method extends keyof Doc['paths'][Path],
+  Path extends DocPath<Doc>,
+  Method extends DocPathMethod<Doc, Path>,
 > = core.RequestHandler<
   PathSchema<Doc, Path, Method>,
   ResponseBodyToJsonSchema<Doc, Path, Method>,
@@ -41,8 +48,8 @@ export type DocRequestHandler<
  */
 export type DocRequestHandlerParams<
   Doc extends RequiredDoc,
-  Path extends DocPathTemplate<Doc>,
-  Method extends keyof Doc['paths'][Path],
+  Path extends DocPath<Doc>,
+  Method extends DocPathMethod<Doc, Path>,
 > = core.RequestHandlerParams<
   PathSchema<Doc, Path, Method>,
   ResponseBodyToJsonSchema<Doc, Path, Method>,
@@ -68,12 +75,28 @@ export interface DocRequestMatcher<
     | 'options'
     | 'head',
 > {
-  <Path extends MethodAwareDocPath<Doc, DocPathTemplate<Doc>, Method>>(
+  <
+    Path extends MethodAwareDocPath<
+      Doc,
+      PathTemplate<Extract<keyof Doc['paths'], string>>,
+      Method
+    >,
+  >(
     path: Path,
-    ...handlers: Array<DocRequestHandler<Doc, Path, Method>>
+    ...handlers: Array<
+      DocRequestHandler<Doc, TemplateToDocPath<Doc, Path>, Method>
+    >
   ): T;
-  <Path extends MethodAwareDocPath<Doc, DocPathTemplate<Doc>, Method>>(
+  <
+    Path extends MethodAwareDocPath<
+      Doc,
+      PathTemplate<Extract<keyof Doc['paths'], string>>,
+      Method
+    >,
+  >(
     path: Path,
-    ...handlers: Array<DocRequestHandlerParams<Doc, Path, Method>>
+    ...handlers: Array<
+      DocRequestHandlerParams<Doc, TemplateToDocPath<Doc, Path>, Method>
+    >
   ): T;
 }
diff --git a/packages/backend-openapi-utils/src/types/params.ts b/packages/backend-openapi-utils/src/types/params.ts
index 52d61a2683..208cbd4e9a 100644
--- a/packages/backend-openapi-utils/src/types/params.ts
+++ b/packages/backend-openapi-utils/src/types/params.ts
@@ -32,7 +32,6 @@ import {
   Filter,
   FullMap,
   MapDiscriminatedUnion,
-  PathTemplate,
   RequiredDoc,
   SchemaRef,
   ValueOf,
@@ -44,9 +43,9 @@ import { FromSchema, JSONSchema7 } from 'json-schema-to-ts';
  */
 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'],
+  Path extends DocPath<Doc>,
+  Method extends DocPathMethod<Doc, Path>,
+  Parameter extends keyof DocOperation<Doc, Path, Method>['parameters'],
 > = DocOperation<
   Doc,
   Path,
@@ -138,33 +137,33 @@ export type ParametersSchema<
  */
 export type HeaderSchema<
   Doc extends RequiredDoc,
-  Path extends PathTemplate<Extract<keyof Doc['paths'], string>>,
+  Path extends DocPath<Doc>,
   Method extends DocPathMethod<Doc, Path>,
-> = ParametersSchema<Doc, DocPath<Doc, Path>, Method, ImmutableHeaderObject>;
+> = ParametersSchema<Doc, Path, Method, ImmutableHeaderObject>;
 
 /**
  * @public
  */
 export type CookieSchema<
   Doc extends RequiredDoc,
-  Path extends PathTemplate<Extract<keyof Doc['paths'], string>>,
+  Path extends DocPath<Doc>,
   Method extends DocPathMethod<Doc, Path>,
-> = ParametersSchema<Doc, DocPath<Doc, Path>, Method, ImmutableCookieObject>;
+> = ParametersSchema<Doc, Path, Method, ImmutableCookieObject>;
 
 /**
  * @public
  */
 export type PathSchema<
   Doc extends RequiredDoc,
-  Path extends PathTemplate<Extract<keyof Doc['paths'], string>>,
+  Path extends DocPath<Doc>,
   Method extends DocPathMethod<Doc, Path>,
-> = ParametersSchema<Doc, DocPath<Doc, Path>, Method, ImmutablePathObject>;
+> = ParametersSchema<Doc, Path, Method, ImmutablePathObject>;
 
 /**
  * @public
  */
 export type QuerySchema<
   Doc extends RequiredDoc,
-  Path extends PathTemplate<Extract<keyof Doc['paths'], string>>,
+  Path extends DocPath<Doc>,
   Method extends DocPathMethod<Doc, Path>,
-> = ParametersSchema<Doc, DocPath<Doc, Path>, Method, ImmutableQueryObject>;
+> = ParametersSchema<Doc, Path, Method, ImmutableQueryObject>;
diff --git a/packages/backend-openapi-utils/src/types/requests.ts b/packages/backend-openapi-utils/src/types/requests.ts
index e6542e186d..99c09bc520 100644
--- a/packages/backend-openapi-utils/src/types/requests.ts
+++ b/packages/backend-openapi-utils/src/types/requests.ts
@@ -26,8 +26,6 @@ import type {
   DocOperation,
   DocPath,
   DocPathMethod,
-  DocPathTemplate,
-  PathTemplate,
   ToTypeSafe,
 } from './common';
 import {
@@ -61,14 +59,10 @@ export type RequestBody<
  */
 export type RequestBodySchema<
   Doc extends RequiredDoc,
-  Path extends DocPathTemplate<Doc>,
+  Path extends DocPath<Doc>,
   Method extends DocPathMethod<Doc, Path>,
-> = RequestBody<
-  Doc,
-  DocPath<Doc, Path>,
-  Method
-> extends ImmutableRequestBodyObject
-  ? ObjectWithContentSchema<Doc, RequestBody<Doc, DocPath<Doc, Path>, Method>>
+> = RequestBody<Doc, Path, Method> extends ImmutableRequestBodyObject
+  ? ObjectWithContentSchema<Doc, RequestBody<Doc, Path, Method>>
   : never;
 
 /**
@@ -77,6 +71,6 @@ export type RequestBodySchema<
  */
 export type RequestBodyToJsonSchema<
   Doc extends RequiredDoc,
-  Path extends PathTemplate<Extract<keyof Doc['paths'], string>>,
+  Path extends DocPath<Doc>,
   Method extends DocPathMethod<Doc, Path>,
 > = ToTypeSafe<RequestBodySchema<Doc, Path, Method>>;
diff --git a/packages/backend-openapi-utils/src/types/responses.ts b/packages/backend-openapi-utils/src/types/responses.ts
index 01e4a12aba..9c58ba7035 100644
--- a/packages/backend-openapi-utils/src/types/responses.ts
+++ b/packages/backend-openapi-utils/src/types/responses.ts
@@ -25,10 +25,9 @@ import type {
   RequiredDoc,
   DocOperation,
   DocPathMethod,
-  DocPathTemplate,
-  PathTemplate,
   ToTypeSafe,
   ValueOf,
+  DocPath,
 } from './common';
 import { ImmutableReferenceObject, ImmutableResponseObject } from './immutable';
 
@@ -37,8 +36,8 @@ import { ImmutableReferenceObject, ImmutableResponseObject } from './immutable';
  */
 export type Response<
   Doc extends RequiredDoc,
-  Path extends keyof Doc['paths'],
-  Method extends keyof Doc['paths'][Path],
+  Path extends DocPath<Doc>,
+  Method extends DocPathMethod<Doc, Path>,
   StatusCode extends keyof DocOperation<Doc, Path, Method>['responses'],
 > = DocOperation<
   Doc,
@@ -59,7 +58,7 @@ export type Response<
  */
 export type ResponseSchemas<
   Doc extends RequiredDoc,
-  Path extends DocPathTemplate<Doc>,
+  Path extends DocPath<Doc>,
   Method extends DocPathMethod<Doc, Path>,
 > = {
   [StatusCode in keyof DocOperation<Doc, Path, Method>['responses']]: Response<
@@ -78,6 +77,6 @@ export type ResponseSchemas<
  */
 export type ResponseBodyToJsonSchema<
   Doc extends RequiredDoc,
-  Path extends PathTemplate<Extract<keyof Doc['paths'], string>>,
+  Path extends DocPath<Doc>,
   Method extends DocPathMethod<Doc, Path>,
 > = ToTypeSafe<ValueOf<ResponseSchemas<Doc, Path, Method>>>;
diff --git a/packages/backend-openapi-utils/src/utility.ts b/packages/backend-openapi-utils/src/utility.ts
new file mode 100644
index 0000000000..d20f615bbb
--- /dev/null
+++ b/packages/backend-openapi-utils/src/utility.ts
@@ -0,0 +1,81 @@
+/*
+ * 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 {
+  CookieSchema,
+  DocPathTemplateMethod,
+  HeaderSchema,
+  PathSchema,
+  PathTemplate,
+  QuerySchema,
+  RequestBodyToJsonSchema,
+  RequiredDoc,
+  ResponseBodyToJsonSchema,
+  TemplateToDocPath,
+} from './types';
+
+/**
+ * @public
+ */
+export type Response<
+  Doc extends RequiredDoc,
+  Path extends PathTemplate<Extract<keyof Doc['paths'], string>>,
+  Method extends DocPathTemplateMethod<Doc, Path>,
+> = ResponseBodyToJsonSchema<Doc, TemplateToDocPath<Doc, Path>, Method>;
+
+/**
+ * @public
+ */
+export type Request<
+  Doc extends RequiredDoc,
+  Path extends PathTemplate<Extract<keyof Doc['paths'], string>>,
+  Method extends DocPathTemplateMethod<Doc, Path>,
+> = RequestBodyToJsonSchema<Doc, TemplateToDocPath<Doc, Path>, Method>;
+
+/**
+ * @public
+ */
+export type HeaderParameters<
+  Doc extends RequiredDoc,
+  Path extends PathTemplate<Extract<keyof Doc['paths'], string>>,
+  Method extends DocPathTemplateMethod<Doc, Path>,
+> = HeaderSchema<Doc, TemplateToDocPath<Doc, Path>, Method>;
+
+/**
+ * @public
+ */
+export type CookieParameters<
+  Doc extends RequiredDoc,
+  Path extends PathTemplate<Extract<keyof Doc['paths'], string>>,
+  Method extends DocPathTemplateMethod<Doc, Path>,
+> = CookieSchema<Doc, TemplateToDocPath<Doc, Path>, Method>;
+
+/**
+ * @public
+ */
+export type PathParameters<
+  Doc extends RequiredDoc,
+  Path extends PathTemplate<Extract<keyof Doc['paths'], string>>,
+  Method extends DocPathTemplateMethod<Doc, Path>,
+> = PathSchema<Doc, TemplateToDocPath<Doc, Path>, Method>;
+
+/**
+ * @public
+ */
+export type QueryParameters<
+  Doc extends RequiredDoc,
+  Path extends PathTemplate<Extract<keyof Doc['paths'], string>>,
+  Method extends DocPathTemplateMethod<Doc, Path>,
+> = QuerySchema<Doc, TemplateToDocPath<Doc, Path>, Method>;
diff --git a/plugins/catalog-backend/src/service/request/parseQueryEntitiesParams.ts b/plugins/catalog-backend/src/service/request/parseQueryEntitiesParams.ts
index b1d5e8dd1f..33033c66f3 100644
--- a/plugins/catalog-backend/src/service/request/parseQueryEntitiesParams.ts
+++ b/plugins/catalog-backend/src/service/request/parseQueryEntitiesParams.ts
@@ -24,10 +24,10 @@ import { parseEntityFilterParams } from './parseEntityFilterParams';
 import { parseEntityOrderFieldParams } from './parseEntityOrderFieldParams';
 import { parseEntityTransformParams } from './parseEntityTransformParams';
 import { spec } from '../../schema/openapi.generated';
-import { internal } from '@backstage/backend-openapi-utils';
+import { QueryParameters } from '@backstage/backend-openapi-utils';
 
 export function parseQueryEntitiesParams(
-  params: internal.QuerySchema<typeof spec, '/entities/by-query', 'get'>,
+  params: QueryParameters<typeof spec, '/entities/by-query', 'get'>,
 ): Omit<QueryEntitiesRequest, 'authorizationToken' | 'limit'> {
   const fields = parseEntityTransformParams(params);
 

From 7c83975531c2e8fb6ba30fca349170b14c3dcc8d Mon Sep 17 00:00:00 2001
From: Aramis Sennyey <aramiss@spotify.com>
Date: Mon, 18 Sep 2023 18:37:41 -0400
Subject: [PATCH 2/4] changeset

Signed-off-by: Aramis Sennyey <aramiss@spotify.com>
---
 .changeset/red-geese-clean.md | 8 ++++++++
 1 file changed, 8 insertions(+)
 create mode 100644 .changeset/red-geese-clean.md

diff --git a/.changeset/red-geese-clean.md b/.changeset/red-geese-clean.md
new file mode 100644
index 0000000000..b4fc9c0808
--- /dev/null
+++ b/.changeset/red-geese-clean.md
@@ -0,0 +1,8 @@
+---
+'@backstage/backend-openapi-utils': patch
+---
+
+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.

From fcd4cf6b9b23e70347fe66b203c4215cbda89884 Mon Sep 17 00:00:00 2001
From: Aramis Sennyey <aramiss@spotify.com>
Date: Mon, 18 Sep 2023 18:54:06 -0400
Subject: [PATCH 3/4] fix export issue

Signed-off-by: Aramis Sennyey <aramiss@spotify.com>
---
 packages/backend-openapi-utils/api-report.md | 50 ++++++++++++++++++--
 packages/backend-openapi-utils/src/index.ts  |  1 +
 2 files changed, 48 insertions(+), 3 deletions(-)

diff --git a/packages/backend-openapi-utils/api-report.md b/packages/backend-openapi-utils/api-report.md
index 26215ad2a5..97ea0224d1 100644
--- a/packages/backend-openapi-utils/api-report.md
+++ b/packages/backend-openapi-utils/api-report.md
@@ -74,6 +74,13 @@ interface CookieObject extends ParameterObject {
   style?: 'form';
 }
 
+// @public (undocumented)
+export type CookieParameters<
+  Doc extends RequiredDoc,
+  Path extends PathTemplate<Extract<keyof Doc['paths'], string>>,
+  Method extends DocPathTemplateMethod<Doc, Path>,
+> = CookieSchema<Doc, TemplateToDocPath<Doc, Path>, Method>;
+
 // @public (undocumented)
 type CookieSchema<
   Doc extends RequiredDoc,
@@ -249,6 +256,13 @@ interface HeaderObject extends ParameterObject {
   style: 'simple';
 }
 
+// @public (undocumented)
+export type HeaderParameters<
+  Doc extends RequiredDoc,
+  Path extends PathTemplate<Extract<keyof Doc['paths'], string>>,
+  Method extends DocPathTemplateMethod<Doc, Path>,
+> = HeaderSchema<Doc, TemplateToDocPath<Doc, Path>, Method>;
+
 // @public (undocumented)
 type HeaderSchema<
   Doc extends RequiredDoc,
@@ -376,7 +390,7 @@ declare namespace internal {
     RequestBody,
     RequestBodySchema,
     RequestBodyToJsonSchema,
-    Response_2 as Response,
+    Response_3 as Response,
     ResponseSchemas,
     ResponseBodyToJsonSchema,
   };
@@ -476,6 +490,13 @@ interface PathObject extends ParameterObject {
   style?: 'simple' | 'label' | 'matrix';
 }
 
+// @public (undocumented)
+export type PathParameters<
+  Doc extends RequiredDoc,
+  Path extends PathTemplate<Extract<keyof Doc['paths'], string>>,
+  Method extends DocPathTemplateMethod<Doc, Path>,
+> = PathSchema<Doc, TemplateToDocPath<Doc, Path>, Method>;
+
 // @public (undocumented)
 type PathSchema<
   Doc extends RequiredDoc,
@@ -518,6 +539,13 @@ interface QueryObject extends ParameterObject {
   style?: 'form' | 'deepObject' | 'pipeDelimited' | 'spaceDelimited';
 }
 
+// @public (undocumented)
+export type QueryParameters<
+  Doc extends RequiredDoc,
+  Path extends PathTemplate<Extract<keyof Doc['paths'], string>>,
+  Method extends DocPathTemplateMethod<Doc, Path>,
+> = QuerySchema<Doc, TemplateToDocPath<Doc, Path>, Method>;
+
 // @public (undocumented)
 type QuerySchema<
   Doc extends RequiredDoc,
@@ -525,6 +553,14 @@ type QuerySchema<
   Method extends DocPathMethod<Doc, Path>,
 > = ParametersSchema<Doc, Path, Method, ImmutableQueryObject>;
 
+// @public (undocumented)
+type Request_2<
+  Doc extends RequiredDoc,
+  Path extends PathTemplate<Extract<keyof Doc['paths'], string>>,
+  Method extends DocPathTemplateMethod<Doc, Path>,
+> = RequestBodyToJsonSchema<Doc, TemplateToDocPath<Doc, Path>, Method>;
+export { Request_2 as Request };
+
 // @public (undocumented)
 type RequestBody<
   Doc extends RequiredDoc,
@@ -574,6 +610,14 @@ type RequiredMap<
 
 // @public (undocumented)
 type Response_2<
+  Doc extends RequiredDoc,
+  Path extends PathTemplate<Extract<keyof Doc['paths'], string>>,
+  Method extends DocPathTemplateMethod<Doc, Path>,
+> = ResponseBodyToJsonSchema<Doc, TemplateToDocPath<Doc, Path>, Method>;
+export { Response_2 as Response };
+
+// @public (undocumented)
+type Response_3<
   Doc extends RequiredDoc,
   Path extends DocPath<Doc>,
   Method extends DocPathMethod<Doc, Path>,
@@ -609,13 +653,13 @@ type ResponseSchemas<
     Doc,
     Path,
     Method
-  >['responses']]: Response_2<
+  >['responses']]: Response_3<
     Doc,
     Path,
     Method,
     StatusCode
   > extends ImmutableResponseObject
-    ? ObjectWithContentSchema<Doc, Response_2<Doc, Path, Method, StatusCode>>
+    ? ObjectWithContentSchema<Doc, Response_3<Doc, Path, Method, StatusCode>>
     : never;
 };
 
diff --git a/packages/backend-openapi-utils/src/index.ts b/packages/backend-openapi-utils/src/index.ts
index 3acdcbf6f0..23df7bb9c6 100644
--- a/packages/backend-openapi-utils/src/index.ts
+++ b/packages/backend-openapi-utils/src/index.ts
@@ -22,5 +22,6 @@
 import * as internal from './types';
 
 export { internal };
+export * from './utility';
 export type { ApiRouter } from './router';
 export { createValidatedOpenApiRouter } from './stub';

From 8863ee2d4620838f69bc36dccd470c356d600bcb Mon Sep 17 00:00:00 2001
From: Aramis Sennyey <aramiss@spotify.com>
Date: Mon, 2 Oct 2023 12:45:49 -0400
Subject: [PATCH 4/4] update to adr4

Signed-off-by: Aramis Sennyey <aramiss@spotify.com>
---
 packages/backend-openapi-utils/src/index.ts | 9 ++++++++-
 1 file changed, 8 insertions(+), 1 deletion(-)

diff --git a/packages/backend-openapi-utils/src/index.ts b/packages/backend-openapi-utils/src/index.ts
index 23df7bb9c6..2b612fd617 100644
--- a/packages/backend-openapi-utils/src/index.ts
+++ b/packages/backend-openapi-utils/src/index.ts
@@ -22,6 +22,13 @@
 import * as internal from './types';
 
 export { internal };
-export * from './utility';
+export type {
+  Request,
+  Response,
+  QueryParameters,
+  HeaderParameters,
+  CookieParameters,
+  PathParameters,
+} from './utility';
 export type { ApiRouter } from './router';
 export { createValidatedOpenApiRouter } from './stub';