@backstage/backend-openapi-utils 0.0.0-nightly-20230407021743

package/CHANGELOG.md

@@ -0,0 +1,7 @@
+# @backstage/backend-openapi-utils
+
+## 0.0.0-nightly-20230407021743
+
+### Patch Changes
+
+- 62fe726fdc5: New plugin! Primary focus is to support types on `Router`s in backend packages. Developers can use the `ApiRouter` from this package in their packages to support a typed experience based on their OpenAPI specs. The `ApiRouter` supports request bodies, response bodies, query parameters and path parameters, as well as full path-based context of the above. This means no more guessing on an endpoint like `req.post('/not-my-route', (req, res)=>{res.send(req.body.badparam)})`. Typescript would catch `/not-my-route`, `req.body.badparam`, `res.send(req.body.badparam)`.

package/README.md

@@ -0,0 +1,45 @@
+# @backstage/openapi-utils
+
+## Summary
+
+This package is meant to provide a typed Express router for an OpenAPI spec. Based on the [`oatx`](https://github.com/varanauskas/oatx) library and adapted to override Express values.
+
+## Getting Started
+
+### Configuration
+
+1. Run `yarn --cwd <package-dir> backstage-cli package schema:openapi:generate` to translate your `src/schema/openapi.yaml` to a new Typescript file in `src/schema/openapi.ts`. In the case of projects that require linting + a license header, you will need to do this manually.
+
+2. In your plugin's `src/service/createRouter.ts`,
+
+```ts
+import {ApiRouter} from `@backstage/backend-openapi-utils`;
+import spec from '../schema/openapi'
+...
+
+export function createRouter(){
+    const router = Router() as ApiRouter<typeof spec>;
+    ...
+}
+```
+
+### Limitations
+
+1. `as const` makes all fields `readonly`
+   To ensure a good DX of using a simple imported JSON spec, we want to remove any type issues between `readonly` arrays and mutable arrays. Typescript does not allow them to be compared, so converting all imports from the `openapi3-ts` library to `readonly` is important. This is achieved through the `ImmutableObject` type in `types/immutable.ts`.
+
+```ts
+...
+// We want an interface like this,
+Router() as ApiRouter<typeof spec>
+
+// Not an interface like this,
+Router() as ApiRouter<DeepWriteable<typeof spec>>
+...
+```
+
+## Future Work
+
+### Runtime validation
+
+Using a package like [`express-openapi-validator`](https://www.npmjs.com/package/express-openapi-validator), would allow us to remove [validation of request bodies with `AJV`](https://github.com/backstage/backstage/blob/master/plugins/catalog-backend/src/service/util.ts#L58). However, `AJV` currently doesn't have support for OpenAPI 3.1 and `express-openapi-validator` enforces full URL matching for paths, meaning it cannot be mounted at the router level.

package/dist/index.cjs.js

@@ -0,0 +1,10 @@
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+var index = /*#__PURE__*/Object.freeze({
+	__proto__: null
+});
+
+exports.internal = index;
+//# sourceMappingURL=index.cjs.js.map

package/dist/index.cjs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.cjs.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;;"}

package/dist/index.d.ts

@@ -0,0 +1,539 @@
+import { JSONSchema7, FromSchema } from 'json-schema-to-ts';
+import { ReferenceObject, OpenAPIObject, ContentObject, RequestBodyObject, ResponseObject, ParameterObject, SchemaObject } from 'openapi3-ts';
+import core from 'express-serve-static-core';
+import { Router } from 'express';
+
+/**
+ * This file is meant to hold Immutable overwrites of the values provided by the `openapi3-ts`
+ *  package due to issues with `as const` supporting only readonly values.
+ */
+/**
+ * From {@link https://github.com/microsoft/TypeScript/issues/13923#issuecomment-653675557}, allows
+ *  us to convert from `as const` to the various OpenAPI types documented in `openapi3-ts`.
+ *
+ * @public
+ */
+type Immutable<T> = T extends Function | boolean | number | string | null | undefined ? T : T extends Map<infer K, infer V> ? ReadonlyMap<Immutable<K>, Immutable<V>> : T extends Set<infer S> ? ReadonlySet<Immutable<S>> : {
+    readonly [P in keyof T]: Immutable<T[P]>;
+};
+/**
+ * @public
+ */
+type ImmutableObject<T> = {
+    readonly [K in keyof T]: Immutable<T[K]>;
+};
+/**
+ * @public
+ */
+type ImmutableReferenceObject = ImmutableObject<ReferenceObject>;
+/**
+ * @public
+ */
+type ImmutableOpenAPIObject = ImmutableObject<OpenAPIObject>;
+/**
+ * @public
+ */
+type ImmutableContentObject = ImmutableObject<ContentObject>;
+/**
+ * @public
+ */
+type ImmutableRequestBodyObject = ImmutableObject<RequestBodyObject>;
+/**
+ * @public
+ */
+type ImmutableResponseObject = ImmutableObject<ResponseObject>;
+/**
+ * @public
+ */
+type ImmutableParameterObject = ImmutableObject<ParameterObject>;
+/**
+ * @public
+ */
+interface HeaderObject extends ParameterObject {
+    in: 'header';
+    style: 'simple';
+}
+/**
+ * @public
+ */
+type ImmutableHeaderObject = ImmutableObject<HeaderObject>;
+/**
+ * @public
+ */
+interface CookieObject extends ParameterObject {
+    in: 'cookie';
+    style?: 'form';
+}
+/**
+ * @public
+ */
+type ImmutableCookieObject = ImmutableObject<CookieObject>;
+/**
+ * @public
+ */
+interface QueryObject extends ParameterObject {
+    in: 'query';
+    style?: 'form' | 'deepObject' | 'pipeDelimited' | 'spaceDelimited';
+}
+/**
+ * @public
+ */
+type ImmutableQueryObject = ImmutableObject<QueryObject>;
+/**
+ * @public
+ */
+interface PathObject extends ParameterObject {
+    in: 'path';
+    style?: 'simple' | 'label' | 'matrix';
+}
+/**
+ * @public
+ */
+type ImmutablePathObject = ImmutableObject<PathObject>;
+/**
+ * @public
+ */
+type ImmutableSchemaObject = ImmutableObject<SchemaObject>;
+
+/**
+ * Pulled from https://github.com/varanauskas/oatx.
+ */
+
+/**
+ * Basic OpenAPI spec with paths and components properties enforced.
+ * @public
+ */
+type RequiredDoc = Pick<ImmutableOpenAPIObject, 'paths' | 'components'>;
+/**
+ * @public
+ */
+type PathDoc = Pick<ImmutableOpenAPIObject, 'paths'>;
+/**
+ * Get value types of `T`.
+ * @public
+ */
+type ValueOf<T> = T[keyof T];
+/**
+ * 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/:postId/comments/:commentId";
+ * const pathWithoutParams: PathTemplate<"/posts/comments"> = "/posts/comments";
+ * ```
+ *
+ * @public
+ */
+type PathTemplate<Path extends string> = Path extends `${infer Prefix}{${infer PathName}}${infer Suffix}` ? `${Prefix}:${PathName}${PathTemplate<Suffix>}` : Path;
+/**
+ * Extract path as specified in OpenAPI `Doc` based on request path
+ * @example
+ * ```ts
+ * const spec = {
+ *   paths: {
+ *       "/posts/{postId}/comments/{commentId}": {},
+ *       "/posts/comments": {},
+ *   }
+ * };
+ * const specPathWithParams: DocPath<typeof spec, "/posts/:postId/comments/:commentId"> = "/posts/{postId}/comments/{commentId}";
+ * const specPathWithoutParams: DocPath<typeof spec, "/posts/comments"> = "/posts/comments";
+ * ```
+ *
+ * @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;
+}>;
+/**
+ * @public
+ */
+type DocPathTemplate<Doc extends PathDoc> = PathTemplate<Extract<keyof Doc['paths'], string>>;
+/**
+ * @public
+ */
+type DocPathMethod<Doc extends Pick<RequiredDoc, 'paths'>, Path extends DocPathTemplate<Doc>> = keyof Doc['paths'][DocPath<Doc, Path>];
+/**
+ * @public
+ */
+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
+ */
+type DocOperation<Doc extends RequiredDoc, Path extends keyof Doc['paths'], Method extends keyof Doc['paths'][Path]> = Doc['paths'][Path][Method];
+/**
+ * @public
+ */
+type ComponentTypes<Doc extends RequiredDoc> = Extract<keyof Doc['components'], string>;
+/**
+ * @public
+ */
+type ComponentRef<Doc extends RequiredDoc, Type extends ComponentTypes<Doc>, Ref extends ImmutableReferenceObject> = Ref extends {
+    $ref: `#/components/${Type}/${infer Name}`;
+} ? Name extends keyof Doc['components'][Type] ? Doc['components'][Type][Name] extends ImmutableReferenceObject ? ComponentRef<Doc, Type, Doc['components'][Type][Name]> : Doc['components'][Type][Name] : never : never;
+/**
+ * @public
+ */
+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
+ */
+type ObjectWithContentSchema<Doc extends RequiredDoc, Object extends {
+    content?: ImmutableContentObject;
+}> = Object['content'] extends ImmutableContentObject ? SchemaRef<Doc, Object['content']['application/json']['schema']> : never;
+/**
+ * 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 ? I : never;
+/**
+ * @public
+ */
+type LastOf<T> = UnionToIntersection<T extends any ? () => T : never> extends () => infer R ? R : never;
+/**
+ * @public
+ */
+type Push<T extends any[], V> = [...T, V];
+/**
+ * @public
+ */
+type TuplifyUnion<T, L = LastOf<T>, N = [T] extends [never] ? true : false> = true extends N ? [] : Push<TuplifyUnion<Exclude<T, L>>, L>;
+/**
+ * @public
+ */
+type ConvertAll<T, R extends ReadonlyArray<unknown> = []> = T extends [
+    infer First extends JSONSchema7,
+    ...infer Rest
+] ? ConvertAll<Rest, [...R, FromSchema<First>]> : R;
+/**
+ * @public
+ */
+type UnknownIfNever<P> = [P] extends [never] ? unknown : P;
+/**
+ * @public
+ */
+type ToTypeSafe<T> = UnknownIfNever<ConvertAll<TuplifyUnion<T>>[number]>;
+/**
+ * @public
+ */
+type DiscriminateUnion<T, K extends keyof T, V extends T[K]> = Extract<T, Record<K, V>>;
+/**
+ * @public
+ */
+type MapDiscriminatedUnion<T extends Record<K, string>, K extends keyof T> = {
+    [V in T[K]]: DiscriminateUnion<T, K, V>;
+};
+/**
+ * @public
+ */
+type PickOptionalKeys<T extends {
+    [key: string]: any;
+}> = {
+    [K in keyof T]: true extends T[K]['required'] ? never : K;
+}[keyof T];
+/**
+ * @public
+ */
+type PickRequiredKeys<T extends {
+    [key: string]: any;
+}> = {
+    [K in keyof T]: true extends T[K]['required'] ? K : never;
+}[keyof T];
+/**
+ * @public
+ */
+type OptionalMap<T extends {
+    [key: string]: any;
+}> = {
+    [P in Exclude<PickOptionalKeys<T>, undefined>]?: NonNullable<T[P]>;
+};
+/**
+ * @public
+ */
+type RequiredMap<T extends {
+    [key: string]: any;
+}> = {
+    [P in Exclude<PickRequiredKeys<T>, undefined>]: NonNullable<T[P]>;
+};
+/**
+ * @public
+ */
+type FullMap<T extends {
+    [key: string]: any;
+}> = RequiredMap<T> & OptionalMap<T>;
+/**
+ * @public
+ */
+type Filter<T, U> = T extends U ? T : never;
+
+/**
+ * @public
+ */
+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']> = DocOperation<Doc, Path, Method>['parameters'][Parameter] extends ImmutableReferenceObject ? 'parameters' extends ComponentTypes<Doc> ? ComponentRef<Doc, 'parameters', DocOperation<Doc, Path, Method>['parameters'][Parameter]> : never : DocOperation<Doc, Path, Method>['parameters'][Parameter];
+/**
+ * @public
+ */
+type DocParameters<Doc extends RequiredDoc, Path extends Extract<keyof Doc['paths'], string>, Method extends keyof Doc['paths'][Path]> = DocOperation<Doc, Path, Method>['parameters'] extends ReadonlyArray<any> ? {
+    [Index in keyof DocOperation<Doc, Path, Method>['parameters']]: DocParameter<Doc, Path, Method, Index>;
+} : never;
+/**
+ * @public
+ */
+type ResolveDocParameterSchema<Doc extends RequiredDoc, Schema extends ImmutableParameterObject['schema']> = Schema extends ImmutableReferenceObject ? 'parameters' extends ComponentTypes<Doc> ? ComponentRef<Doc, 'parameters', Schema> : never : Schema;
+/**
+ * @public
+ */
+type ParameterSchema<Doc extends RequiredDoc, Schema extends ImmutableParameterObject['schema']> = ResolveDocParameterSchema<Doc, Schema> extends infer R ? R extends ImmutableSchemaObject ? R extends JSONSchema7 ? FromSchema<R> : never : never : never;
+/**
+ * @public
+ */
+type MapToSchema<Doc extends RequiredDoc, T extends Record<string, ImmutableParameterObject>> = {
+    [V in keyof T]: NonNullable<T[V]> extends ImmutableParameterObject ? ParameterSchema<Doc, NonNullable<T[V]>['schema']> : never;
+};
+/**
+ * @public
+ */
+type ParametersSchema<Doc extends RequiredDoc, Path extends Extract<keyof Doc['paths'], string>, Method extends keyof Doc['paths'][Path], FilterType extends ImmutableParameterObject> = number extends keyof DocParameters<Doc, Path, Method> ? MapToSchema<Doc, FullMap<MapDiscriminatedUnion<Filter<DocParameters<Doc, Path, Method>[number], FilterType>, 'name'>>> : never;
+/**
+ * @public
+ */
+type HeaderSchema<Doc extends RequiredDoc, Path extends PathTemplate<Extract<keyof Doc['paths'], string>>, Method extends DocPathMethod<Doc, Path>> = ParametersSchema<Doc, DocPath<Doc, Path>, Method, ImmutableHeaderObject>;
+/**
+ * @public
+ */
+type CookieSchema<Doc extends RequiredDoc, Path extends PathTemplate<Extract<keyof Doc['paths'], string>>, Method extends DocPathMethod<Doc, Path>> = ParametersSchema<Doc, DocPath<Doc, Path>, Method, ImmutableCookieObject>;
+/**
+ * @public
+ */
+type PathSchema<Doc extends RequiredDoc, Path extends PathTemplate<Extract<keyof Doc['paths'], string>>, Method extends DocPathMethod<Doc, Path>> = ParametersSchema<Doc, DocPath<Doc, Path>, Method, ImmutablePathObject>;
+/**
+ * @public
+ */
+type QuerySchema<Doc extends RequiredDoc, Path extends PathTemplate<Extract<keyof Doc['paths'], string>>, Method extends DocPathMethod<Doc, Path>> = ParametersSchema<Doc, DocPath<Doc, Path>, Method, ImmutableQueryObject>;
+
+/**
+ * Pulled from https://github.com/varanauskas/oatx.
+ */
+
+/**
+ * @public
+ */
+type RequestBody<Doc extends RequiredDoc, Path extends Extract<keyof Doc['paths'], string>, Method extends keyof Doc['paths'][Path]> = DocOperation<Doc, Path, Method>['requestBody'] extends ImmutableReferenceObject ? 'requestBodies' extends ComponentTypes<Doc> ? ComponentRef<Doc, 'requestBodies', DocOperation<Doc, Path, Method>['requestBody']> : never : DocOperation<Doc, Path, Method>['requestBody'];
+/**
+ * @public
+ */
+type RequestBodySchema<Doc extends RequiredDoc, Path extends DocPathTemplate<Doc>, Method extends DocPathMethod<Doc, Path>> = RequestBody<Doc, DocPath<Doc, Path>, Method> extends ImmutableRequestBodyObject ? ObjectWithContentSchema<Doc, RequestBody<Doc, DocPath<Doc, Path>, Method>> : never;
+/**
+ * Transform the OpenAPI request body schema to a typesafe JSON schema.
+ * @public
+ */
+type RequestBodyToJsonSchema<Doc extends RequiredDoc, Path extends PathTemplate<Extract<keyof Doc['paths'], string>>, Method extends DocPathMethod<Doc, Path>> = ToTypeSafe<RequestBodySchema<Doc, Path, Method>>;
+
+/**
+ * Pulled from https://github.com/varanauskas/oatx.
+ */
+
+/**
+ * @public
+ */
+type Response<Doc extends RequiredDoc, Path extends keyof Doc['paths'], Method extends keyof Doc['paths'][Path], StatusCode extends keyof DocOperation<Doc, Path, Method>['responses']> = DocOperation<Doc, Path, Method>['responses'][StatusCode] extends ImmutableReferenceObject ? 'responses' extends ComponentTypes<Doc> ? ComponentRef<Doc, 'responses', DocOperation<Doc, Path, Method>['responses'][StatusCode]> : never : DocOperation<Doc, Path, Method>['responses'][StatusCode];
+/**
+ * @public
+ */
+type ResponseSchemas<Doc extends RequiredDoc, Path extends DocPathTemplate<Doc>, Method extends DocPathMethod<Doc, Path>> = {
+    [StatusCode in keyof DocOperation<Doc, Path, Method>['responses']]: Response<Doc, Path, Method, StatusCode> extends ImmutableResponseObject ? ObjectWithContentSchema<Doc, Response<Doc, Path, Method, StatusCode>> : never;
+};
+/**
+ * Transform the OpenAPI request body schema to a typesafe JSON schema.
+ * @public
+ */
+type ResponseBodyToJsonSchema<Doc extends RequiredDoc, Path extends PathTemplate<Extract<keyof Doc['paths'], string>>, Method extends DocPathMethod<Doc, Path>> = ToTypeSafe<ValueOf<ResponseSchemas<Doc, Path, Method>>>;
+
+/**
+ * Typed express request handler.
+ * @public
+ */
+type DocRequestHandler<Doc extends RequiredDoc, Path extends DocPathTemplate<Doc>, Method extends keyof Doc['paths'][Path]> = core.RequestHandler<PathSchema<Doc, Path, Method>, ResponseBodyToJsonSchema<Doc, Path, Method>, RequestBodyToJsonSchema<Doc, Path, Method>, QuerySchema<Doc, Path, Method>, Record<string, string>>;
+/**
+ * Typed express error handler / request handler union type.
+ * @public
+ */
+type DocRequestHandlerParams<Doc extends RequiredDoc, Path extends DocPathTemplate<Doc>, Method extends keyof Doc['paths'][Path]> = core.RequestHandlerParams<PathSchema<Doc, Path, Method>, ResponseBodyToJsonSchema<Doc, Path, Method>, RequestBodyToJsonSchema<Doc, Path, Method>, QuerySchema<Doc, Path, Method>, Record<string, string>>;
+/**
+ * Superset of the express router path matcher that enforces typed request and response bodies.
+ * @public
+ */
+interface DocRequestMatcher<Doc extends RequiredDoc, T, Method extends 'all' | 'get' | 'post' | 'put' | 'delete' | 'patch' | 'options' | 'head'> {
+    <Path extends MethodAwareDocPath<Doc, DocPathTemplate<Doc>, Method>>(path: Path, ...handlers: Array<DocRequestHandler<Doc, Path, Method>>): T;
+    <Path extends MethodAwareDocPath<Doc, DocPathTemplate<Doc>, Method>>(path: Path, ...handlers: Array<DocRequestHandlerParams<Doc, Path, Method>>): T;
+}
+
+type index_d_RequiredDoc = RequiredDoc;
+type index_d_PathDoc = PathDoc;
+type index_d_ValueOf<T> = ValueOf<T>;
+type index_d_PathTemplate<Path extends string> = PathTemplate<Path>;
+type index_d_DocPath<Doc extends PathDoc, Path extends PathTemplate<Extract<keyof Doc['paths'], string>>> = DocPath<Doc, Path>;
+type index_d_DocPathTemplate<Doc extends PathDoc> = DocPathTemplate<Doc>;
+type index_d_DocPathMethod<Doc extends Pick<RequiredDoc, 'paths'>, Path extends DocPathTemplate<Doc>> = DocPathMethod<Doc, Path>;
+type index_d_MethodAwareDocPath<Doc extends PathDoc, Path extends PathTemplate<Extract<keyof Doc['paths'], string>>, Method extends keyof Doc['paths'][Path]> = MethodAwareDocPath<Doc, Path, Method>;
+type index_d_DocOperation<Doc extends RequiredDoc, Path extends keyof Doc['paths'], Method extends keyof Doc['paths'][Path]> = DocOperation<Doc, Path, Method>;
+type index_d_ComponentTypes<Doc extends RequiredDoc> = ComponentTypes<Doc>;
+type index_d_ComponentRef<Doc extends RequiredDoc, Type extends ComponentTypes<Doc>, Ref extends ImmutableReferenceObject> = ComponentRef<Doc, Type, Ref>;
+type index_d_SchemaRef<Doc extends RequiredDoc, Schema> = SchemaRef<Doc, Schema>;
+type index_d_ObjectWithContentSchema<Doc extends RequiredDoc, Object extends {
+    content?: ImmutableContentObject;
+}> = ObjectWithContentSchema<Doc, Object>;
+type index_d_UnionToIntersection<U> = UnionToIntersection<U>;
+type index_d_LastOf<T> = LastOf<T>;
+type index_d_Push<T extends any[], V> = Push<T, V>;
+type index_d_TuplifyUnion<T, L = LastOf<T>, N = [T] extends [never] ? true : false> = TuplifyUnion<T, L, N>;
+type index_d_ConvertAll<T, R extends ReadonlyArray<unknown> = []> = ConvertAll<T, R>;
+type index_d_UnknownIfNever<P> = UnknownIfNever<P>;
+type index_d_ToTypeSafe<T> = ToTypeSafe<T>;
+type index_d_DiscriminateUnion<T, K extends keyof T, V extends T[K]> = DiscriminateUnion<T, K, V>;
+type index_d_MapDiscriminatedUnion<T extends Record<K, string>, K extends keyof T> = MapDiscriminatedUnion<T, K>;
+type index_d_PickOptionalKeys<T extends {
+    [key: string]: any;
+}> = PickOptionalKeys<T>;
+type index_d_PickRequiredKeys<T extends {
+    [key: string]: any;
+}> = PickRequiredKeys<T>;
+type index_d_OptionalMap<T extends {
+    [key: string]: any;
+}> = OptionalMap<T>;
+type index_d_RequiredMap<T extends {
+    [key: string]: any;
+}> = RequiredMap<T>;
+type index_d_FullMap<T extends {
+    [key: string]: any;
+}> = FullMap<T>;
+type index_d_Filter<T, U> = Filter<T, U>;
+type index_d_DocRequestHandler<Doc extends RequiredDoc, Path extends DocPathTemplate<Doc>, Method extends keyof Doc['paths'][Path]> = DocRequestHandler<Doc, Path, Method>;
+type index_d_DocRequestHandlerParams<Doc extends RequiredDoc, Path extends DocPathTemplate<Doc>, Method extends keyof Doc['paths'][Path]> = DocRequestHandlerParams<Doc, Path, Method>;
+type index_d_DocRequestMatcher<Doc extends RequiredDoc, T, Method extends 'all' | 'get' | 'post' | 'put' | 'delete' | 'patch' | 'options' | 'head'> = DocRequestMatcher<Doc, T, Method>;
+type index_d_Immutable<T> = Immutable<T>;
+type index_d_ImmutableObject<T> = ImmutableObject<T>;
+type index_d_ImmutableReferenceObject = ImmutableReferenceObject;
+type index_d_ImmutableOpenAPIObject = ImmutableOpenAPIObject;
+type index_d_ImmutableContentObject = ImmutableContentObject;
+type index_d_ImmutableRequestBodyObject = ImmutableRequestBodyObject;
+type index_d_ImmutableResponseObject = ImmutableResponseObject;
+type index_d_ImmutableParameterObject = ImmutableParameterObject;
+type index_d_HeaderObject = HeaderObject;
+type index_d_ImmutableHeaderObject = ImmutableHeaderObject;
+type index_d_CookieObject = CookieObject;
+type index_d_ImmutableCookieObject = ImmutableCookieObject;
+type index_d_QueryObject = QueryObject;
+type index_d_ImmutableQueryObject = ImmutableQueryObject;
+type index_d_PathObject = PathObject;
+type index_d_ImmutablePathObject = ImmutablePathObject;
+type index_d_ImmutableSchemaObject = ImmutableSchemaObject;
+type index_d_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']> = DocParameter<Doc, Path, Method, Parameter>;
+type index_d_DocParameters<Doc extends RequiredDoc, Path extends Extract<keyof Doc['paths'], string>, Method extends keyof Doc['paths'][Path]> = DocParameters<Doc, Path, Method>;
+type index_d_ResolveDocParameterSchema<Doc extends RequiredDoc, Schema extends ImmutableParameterObject['schema']> = ResolveDocParameterSchema<Doc, Schema>;
+type index_d_ParameterSchema<Doc extends RequiredDoc, Schema extends ImmutableParameterObject['schema']> = ParameterSchema<Doc, Schema>;
+type index_d_MapToSchema<Doc extends RequiredDoc, T extends Record<string, ImmutableParameterObject>> = MapToSchema<Doc, T>;
+type index_d_ParametersSchema<Doc extends RequiredDoc, Path extends Extract<keyof Doc['paths'], string>, Method extends keyof Doc['paths'][Path], FilterType extends ImmutableParameterObject> = ParametersSchema<Doc, Path, Method, FilterType>;
+type index_d_HeaderSchema<Doc extends RequiredDoc, Path extends PathTemplate<Extract<keyof Doc['paths'], string>>, Method extends DocPathMethod<Doc, Path>> = HeaderSchema<Doc, Path, Method>;
+type index_d_CookieSchema<Doc extends RequiredDoc, Path extends PathTemplate<Extract<keyof Doc['paths'], string>>, Method extends DocPathMethod<Doc, Path>> = CookieSchema<Doc, Path, Method>;
+type index_d_PathSchema<Doc extends RequiredDoc, Path extends PathTemplate<Extract<keyof Doc['paths'], string>>, Method extends DocPathMethod<Doc, Path>> = PathSchema<Doc, Path, Method>;
+type index_d_QuerySchema<Doc extends RequiredDoc, Path extends PathTemplate<Extract<keyof Doc['paths'], string>>, Method extends DocPathMethod<Doc, Path>> = QuerySchema<Doc, Path, Method>;
+type index_d_RequestBody<Doc extends RequiredDoc, Path extends Extract<keyof Doc['paths'], string>, Method extends keyof Doc['paths'][Path]> = RequestBody<Doc, Path, Method>;
+type index_d_RequestBodySchema<Doc extends RequiredDoc, Path extends DocPathTemplate<Doc>, Method extends DocPathMethod<Doc, Path>> = RequestBodySchema<Doc, Path, Method>;
+type index_d_RequestBodyToJsonSchema<Doc extends RequiredDoc, Path extends PathTemplate<Extract<keyof Doc['paths'], string>>, Method extends DocPathMethod<Doc, Path>> = RequestBodyToJsonSchema<Doc, Path, Method>;
+type index_d_Response<Doc extends RequiredDoc, Path extends keyof Doc['paths'], Method extends keyof Doc['paths'][Path], StatusCode extends keyof DocOperation<Doc, Path, Method>['responses']> = Response<Doc, Path, Method, StatusCode>;
+type index_d_ResponseSchemas<Doc extends RequiredDoc, Path extends DocPathTemplate<Doc>, Method extends DocPathMethod<Doc, Path>> = ResponseSchemas<Doc, Path, Method>;
+type index_d_ResponseBodyToJsonSchema<Doc extends RequiredDoc, Path extends PathTemplate<Extract<keyof Doc['paths'], string>>, Method extends DocPathMethod<Doc, Path>> = ResponseBodyToJsonSchema<Doc, Path, Method>;
+declare namespace index_d {
+  export {
+    index_d_RequiredDoc as RequiredDoc,
+    index_d_PathDoc as PathDoc,
+    index_d_ValueOf as ValueOf,
+    index_d_PathTemplate as PathTemplate,
+    index_d_DocPath as DocPath,
+    index_d_DocPathTemplate as DocPathTemplate,
+    index_d_DocPathMethod as DocPathMethod,
+    index_d_MethodAwareDocPath as MethodAwareDocPath,
+    index_d_DocOperation as DocOperation,
+    index_d_ComponentTypes as ComponentTypes,
+    index_d_ComponentRef as ComponentRef,
+    index_d_SchemaRef as SchemaRef,
+    index_d_ObjectWithContentSchema as ObjectWithContentSchema,
+    index_d_UnionToIntersection as UnionToIntersection,
+    index_d_LastOf as LastOf,
+    index_d_Push as Push,
+    index_d_TuplifyUnion as TuplifyUnion,
+    index_d_ConvertAll as ConvertAll,
+    index_d_UnknownIfNever as UnknownIfNever,
+    index_d_ToTypeSafe as ToTypeSafe,
+    index_d_DiscriminateUnion as DiscriminateUnion,
+    index_d_MapDiscriminatedUnion as MapDiscriminatedUnion,
+    index_d_PickOptionalKeys as PickOptionalKeys,
+    index_d_PickRequiredKeys as PickRequiredKeys,
+    index_d_OptionalMap as OptionalMap,
+    index_d_RequiredMap as RequiredMap,
+    index_d_FullMap as FullMap,
+    index_d_Filter as Filter,
+    index_d_DocRequestHandler as DocRequestHandler,
+    index_d_DocRequestHandlerParams as DocRequestHandlerParams,
+    index_d_DocRequestMatcher as DocRequestMatcher,
+    index_d_Immutable as Immutable,
+    index_d_ImmutableObject as ImmutableObject,
+    index_d_ImmutableReferenceObject as ImmutableReferenceObject,
+    index_d_ImmutableOpenAPIObject as ImmutableOpenAPIObject,
+    index_d_ImmutableContentObject as ImmutableContentObject,
+    index_d_ImmutableRequestBodyObject as ImmutableRequestBodyObject,
+    index_d_ImmutableResponseObject as ImmutableResponseObject,
+    index_d_ImmutableParameterObject as ImmutableParameterObject,
+    index_d_HeaderObject as HeaderObject,
+    index_d_ImmutableHeaderObject as ImmutableHeaderObject,
+    index_d_CookieObject as CookieObject,
+    index_d_ImmutableCookieObject as ImmutableCookieObject,
+    index_d_QueryObject as QueryObject,
+    index_d_ImmutableQueryObject as ImmutableQueryObject,
+    index_d_PathObject as PathObject,
+    index_d_ImmutablePathObject as ImmutablePathObject,
+    index_d_ImmutableSchemaObject as ImmutableSchemaObject,
+    index_d_DocParameter as DocParameter,
+    index_d_DocParameters as DocParameters,
+    index_d_ResolveDocParameterSchema as ResolveDocParameterSchema,
+    index_d_ParameterSchema as ParameterSchema,
+    index_d_MapToSchema as MapToSchema,
+    index_d_ParametersSchema as ParametersSchema,
+    index_d_HeaderSchema as HeaderSchema,
+    index_d_CookieSchema as CookieSchema,
+    index_d_PathSchema as PathSchema,
+    index_d_QuerySchema as QuerySchema,
+    index_d_RequestBody as RequestBody,
+    index_d_RequestBodySchema as RequestBodySchema,
+    index_d_RequestBodyToJsonSchema as RequestBodyToJsonSchema,
+    index_d_Response as Response,
+    index_d_ResponseSchemas as ResponseSchemas,
+    index_d_ResponseBodyToJsonSchema as ResponseBodyToJsonSchema,
+  };
+}
+
+/**
+ * Typed Express router based on an OpenAPI 3.1 spec.
+ * @public
+ */
+interface ApiRouter<Doc extends RequiredDoc> extends Router {
+    get: DocRequestMatcher<Doc, this, 'get'>;
+    post: DocRequestMatcher<Doc, this, 'post'>;
+    all: DocRequestMatcher<Doc, this, 'all'>;
+    put: DocRequestMatcher<Doc, this, 'put'>;
+    delete: DocRequestMatcher<Doc, this, 'delete'>;
+    patch: DocRequestMatcher<Doc, this, 'patch'>;
+    options: DocRequestMatcher<Doc, this, 'options'>;
+    head: DocRequestMatcher<Doc, this, 'head'>;
+}
+
+export { ApiRouter, index_d as internal };

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@backstage/backend-openapi-utils",
+  "description": "OpenAPI typescript support.",
+  "version": "0.0.0-nightly-20230407021743",
+  "main": "dist/index.cjs.js",
+  "types": "dist/index.d.ts",
+  "license": "Apache-2.0",
+  "publishConfig": {
+    "access": "public",
+    "main": "dist/index.cjs.js",
+    "module": "dist/index.esm.js",
+    "types": "dist/index.d.ts"
+  },
+  "backstage": {
+    "role": "node-library"
+  },
+  "scripts": {
+    "start": "backstage-cli package start",
+    "build": "backstage-cli package build",
+    "lint": "backstage-cli package lint",
+    "test": "backstage-cli package test",
+    "clean": "backstage-cli package clean",
+    "prepack": "backstage-cli package prepack",
+    "postpack": "backstage-cli package postpack"
+  },
+  "devDependencies": {
+    "@backstage/cli": "^0.0.0-nightly-20230407021743"
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@types/express": "^4.17.6",
+    "@types/express-serve-static-core": "^4.17.5",
+    "express": "^4.17.1",
+    "express-promise-router": "^4.1.0",
+    "json-schema-to-ts": "^2.6.2",
+    "openapi3-ts": "^3.1.2"
+  },
+  "module": "dist/index.esm.js"
+}