Create + update API report.

Signed-off-by: Aramis Sennyey <sennyeya@amazon.com>
2023-02-22 18:32:53 -05:00
parent 20b79e8110
commit a71d26fabf
8 changed files with 467 additions and 23 deletions
@@ -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];
+```
@@ -20,4 +20,5 @@
 * @packageDocumentation
 */

-export * from './router';
+export type { ApiRouter } from './router';
+export * from './types';
@@ -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'>;

@@ -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]>;
@@ -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,
@@ -14,4 +14,6 @@
 * limitations under the License.
 */
 export * from './common';
+export * from './express';
 export * from './requests';
+export * from './responses';
@@ -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>>,
@@ -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>>,