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] 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>>,