@backstage/backend-openapi-utils 0.0.2-next.1 → 0.0.3-next.0

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # @backstage/backend-openapi-utils
 
+## 0.0.3-next.0
+
+### Patch Changes
+
+- ebeb77586975: Add a new `createRouter` method for generating an `express` router that validates against your spec. Also fixes a bug with the query parameters type resolution.
+- Updated dependencies
+  - @backstage/errors@1.2.1
+
+## 0.0.2
+
+### Patch Changes
+
+- fe16bd39e83: Use permalinks for links including a line number reference
+- 27956d78671: Adjusted README accordingly after the generated output now has a `.generated.ts` extension
+- 021cfbb5152: Corrected resolution of parameter nested schema to use central schemas.
+- 799c33047ed: Updated README to reflect changes in `@backstage/repo-tools`.
+
 ## 0.0.2-next.1
 
 ### Patch Changes

package/README.md

@@ -8,21 +8,61 @@ This package is meant to provide a typed Express router for an OpenAPI spec. Bas
 
 ### 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.generated.ts`. The command will try to execute both a lint and prettier step on the generated file, where applicable.
+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.generated.ts`. The command will try to execute both a lint and prettier step on the generated file, where applicable.
 
 2. In your plugin's `src/service/createRouter.ts`,
 
 ```ts
-import { ApiRouter } from `@backstage/backend-openapi-utils`;
-import spec from '../schema/openapi.generated';
+import { createOpenApiRouter } from '../schema/openapi.generated';
 // ...
 export function createRouter() {
-    const router = Router() as ApiRouter<typeof spec>;
-    // ...
-    return router;
+  const router = createOpenApiRouter();
+  // add routes to router, it's just an express router.
+  return router;
 }
 ```
 
+3. Add `@backstage/backend-openapi-utils` to your `package.json`'s `dependencies`.
+
+Why do I need to add this to `dependencies`? If you check the `src/schema/openapi.generated.ts` file, we're creating a router stub for you with the `@backstage/backend-openapi-utils` package.
+
+### Customization
+
+If the out of the box `router` doesn't work, you can do the following,
+
+```ts
+import { createOpenApiRouter } from '../schema/openapi.generated';
+// ...
+export function createRouter() {
+  // See https://github.com/cdimascio/express-openapi-validator/wiki/Documentation for available options.
+  const router = createOpenApiRouter(validatorOptions);
+  // add routes to router, it's just an express router.
+  return router;
+}
+```
+
+If you need even more control -- say for example you wanted to update the spec at runtime -- you can do the following,
+
+```ts
+import { spec } from '../schema/openapi.generated';
+import { createValidatedOpenApiRouter } from '@backstage/backend-openapi-utils';
+// ...
+export function createRouter() {
+  // Update the spec here.
+  const newSpec = { ...spec, myproperty123: 123 };
+
+  // See https://github.com/cdimascio/express-openapi-validator/wiki/Documentation for available options.
+  const router = createValidatedOpenApiRouter<typeof newSpec>(
+    newSpec,
+    validatorOptions,
+  );
+  // add routes to router, it's just an express router.
+  return router;
+}
+```
+
+## INTERNAL
+
 ### Limitations
 
 1. `as const` makes all fields `readonly`
@@ -40,6 +80,10 @@ Router() as ApiRouter<DeepWriteable<typeof spec>>
 
 ## Future Work
 
-### Runtime validation
+### Response Validation
+
+This is a murky ground and something that will take a while to gain adoption. For now, keep responses in the spec and at the type level, but will need to work to drive adoption of response validation.
+
+### Common Error Format
 
-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/e0506af8fc54074a160fb91c83d6cae8172d3bb3/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.
+With the new `createRouter` method, we can start to control error response formats for input and coercion errors.

package/dist/index.cjs.js

@@ -2,9 +2,64 @@
 
 Object.defineProperty(exports, '__esModule', { value: true });
 
+var PromiseRouter = require('express-promise-router');
+var express = require('express');
+var errors = require('@backstage/errors');
+var expressOpenapiValidator = require('express-openapi-validator');
+
+function _interopDefaultLegacy (e) { return e && typeof e === 'object' && 'default' in e ? e : { 'default': e }; }
+
+var PromiseRouter__default = /*#__PURE__*/_interopDefaultLegacy(PromiseRouter);
+
 var index = /*#__PURE__*/Object.freeze({
-	__proto__: null
+  __proto__: null
 });
 
+const baseUrlSymbol = Symbol();
+const originalUrlSymbol = Symbol();
+function validatorErrorTransformer() {
+  return (error, _, _2, next) => {
+    next(new errors.InputError(error.message));
+  };
+}
+function getDefaultRouterMiddleware() {
+  return [express.json()];
+}
+function createValidatedOpenApiRouter(spec, options) {
+  const router = PromiseRouter__default["default"]();
+  router.use((options == null ? void 0 : options.middleware) || getDefaultRouterMiddleware());
+  router.use((req, _, next) => {
+    const customRequest = req;
+    customRequest[baseUrlSymbol] = customRequest.baseUrl;
+    customRequest.baseUrl = "";
+    customRequest[originalUrlSymbol] = customRequest.originalUrl;
+    customRequest.originalUrl = customRequest.url;
+    next();
+  });
+  router.use(
+    expressOpenapiValidator.middleware({
+      validateRequests: {
+        coerceTypes: false,
+        allowUnknownQueryParameters: false
+      },
+      ignoreUndocumented: true,
+      validateResponses: false,
+      ...options == null ? void 0 : options.validatorOptions,
+      apiSpec: spec
+    })
+  );
+  router.use((req, _, next) => {
+    const customRequest = req;
+    customRequest.baseUrl = customRequest[baseUrlSymbol];
+    customRequest.originalUrl = customRequest[originalUrlSymbol];
+    delete customRequest[baseUrlSymbol];
+    delete customRequest[originalUrlSymbol];
+    next();
+  });
+  router.use(validatorErrorTransformer());
+  return router;
+}
+
+exports.createValidatedOpenApiRouter = createValidatedOpenApiRouter;
 exports.internal = index;
 //# sourceMappingURL=index.cjs.js.map

package/dist/index.cjs.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.cjs.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;;"}
+{"version":3,"file":"index.cjs.js","sources":["../src/stub.ts"],"sourcesContent":["/*\n * Copyright 2023 The Backstage Authors\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *     http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport PromiseRouter from 'express-promise-router';\nimport { ApiRouter } from './router';\nimport { RequiredDoc } from './types';\nimport {\n  ErrorRequestHandler,\n  RequestHandler,\n  NextFunction,\n  Request,\n  Response,\n  json,\n} from 'express';\nimport { InputError } from '@backstage/errors';\nimport { middleware as OpenApiValidator } from 'express-openapi-validator';\n\ntype PropertyOverrideRequest = Request & {\n  [key: symbol]: string;\n};\n\nconst baseUrlSymbol = Symbol();\nconst originalUrlSymbol = Symbol();\n\nfunction validatorErrorTransformer(): ErrorRequestHandler {\n  return (error: Error, _: Request, _2: Response, next: NextFunction) => {\n    next(new InputError(error.message));\n  };\n}\n\nexport function getDefaultRouterMiddleware() {\n  return [json()];\n}\n\n/**\n * Create a new OpenAPI router with some default middleware.\n * @param spec - Your OpenAPI spec imported as a JSON object.\n * @param validatorOptions - `openapi-express-validator` options to override the defaults.\n * @returns A new express router with validation middleware.\n * @public\n */\nexport function createValidatedOpenApiRouter<T extends RequiredDoc>(\n  spec: T,\n  options?: {\n    validatorOptions?: Partial<Parameters<typeof OpenApiValidator>['0']>;\n    middleware?: RequestHandler[];\n  },\n) {\n  const router = PromiseRouter() as ApiRouter<typeof spec>;\n  router.use(options?.middleware || getDefaultRouterMiddleware());\n\n  /**\n   * Middleware to setup the routing for OpenApiValidator. OpenApiValidator expects `req.originalUrl`\n   *    and `req.baseUrl` to be the full path. We adjust them here to basically be nothing and then\n   *    revive the old values in the last function in this method. We could instead update `req.path`\n   *    but that might affect the routing and I'd rather not.\n   *\n   * TODO: I opened https://github.com/cdimascio/express-openapi-validator/issues/843\n   *    to track this on the middleware side, but there was a similar ticket, https://github.com/cdimascio/express-openapi-validator/issues/113\n   *    that has had minimal activity. If that changes, update this to use a new option on their side.\n   */\n  router.use((req: Request, _, next) => {\n    /**\n     * Express typings are weird. They don't recognize PropertyOverrideRequest as a valid\n     *  Request child and try to overload as PathParams. Just cast it here, since we know\n     *  what we're doing.\n     */\n    const customRequest = req as PropertyOverrideRequest;\n    customRequest[baseUrlSymbol] = customRequest.baseUrl;\n    customRequest.baseUrl = '';\n    customRequest[originalUrlSymbol] = customRequest.originalUrl;\n    customRequest.originalUrl = customRequest.url;\n    next();\n  });\n\n  // TODO: Handle errors by converting from OpenApiValidator errors to known @backstage/errors errors.\n  router.use(\n    OpenApiValidator({\n      validateRequests: {\n        coerceTypes: false,\n        allowUnknownQueryParameters: false,\n      },\n      ignoreUndocumented: true,\n      validateResponses: false,\n      ...options?.validatorOptions,\n      apiSpec: spec as any,\n    }),\n  );\n\n  /**\n   * Revert `req.baseUrl` and `req.originalUrl` changes. This ensures that any further usage\n   *    of these variables will be unchanged.\n   */\n  router.use((req: Request, _, next) => {\n    const customRequest = req as PropertyOverrideRequest;\n    customRequest.baseUrl = customRequest[baseUrlSymbol];\n    customRequest.originalUrl = customRequest[originalUrlSymbol];\n    delete customRequest[baseUrlSymbol];\n    delete customRequest[originalUrlSymbol];\n    next();\n  });\n\n  // Any errors from the middleware get through here.\n  router.use(validatorErrorTransformer());\n\n  return router;\n}\n"],"names":["InputError","json","PromiseRouter","OpenApiValidator"],"mappings":";;;;;;;;;;;;;;;;;AAkCA,MAAM,gBAAgB,MAAO,EAAA,CAAA;AAC7B,MAAM,oBAAoB,MAAO,EAAA,CAAA;AAEjC,SAAS,yBAAiD,GAAA;AACxD,EAAA,OAAO,CAAC,KAAA,EAAc,CAAY,EAAA,EAAA,EAAc,IAAuB,KAAA;AACrE,IAAA,IAAA,CAAK,IAAIA,iBAAA,CAAW,KAAM,CAAA,OAAO,CAAC,CAAA,CAAA;AAAA,GACpC,CAAA;AACF,CAAA;AAEO,SAAS,0BAA6B,GAAA;AAC3C,EAAO,OAAA,CAACC,cAAM,CAAA,CAAA;AAChB,CAAA;AASgB,SAAA,4BAAA,CACd,MACA,OAIA,EAAA;AACA,EAAA,MAAM,SAASC,iCAAc,EAAA,CAAA;AAC7B,EAAA,MAAA,CAAO,GAAI,CAAA,CAAA,OAAA,IAAA,IAAA,GAAA,KAAA,CAAA,GAAA,OAAA,CAAS,UAAc,KAAA,0BAAA,EAA4B,CAAA,CAAA;AAY9D,EAAA,MAAA,CAAO,GAAI,CAAA,CAAC,GAAc,EAAA,CAAA,EAAG,IAAS,KAAA;AAMpC,IAAA,MAAM,aAAgB,GAAA,GAAA,CAAA;AACtB,IAAc,aAAA,CAAA,aAAa,IAAI,aAAc,CAAA,OAAA,CAAA;AAC7C,IAAA,aAAA,CAAc,OAAU,GAAA,EAAA,CAAA;AACxB,IAAc,aAAA,CAAA,iBAAiB,IAAI,aAAc,CAAA,WAAA,CAAA;AACjD,IAAA,aAAA,CAAc,cAAc,aAAc,CAAA,GAAA,CAAA;AAC1C,IAAK,IAAA,EAAA,CAAA;AAAA,GACN,CAAA,CAAA;AAGD,EAAO,MAAA,CAAA,GAAA;AAAA,IACLC,kCAAiB,CAAA;AAAA,MACf,gBAAkB,EAAA;AAAA,QAChB,WAAa,EAAA,KAAA;AAAA,QACb,2BAA6B,EAAA,KAAA;AAAA,OAC/B;AAAA,MACA,kBAAoB,EAAA,IAAA;AAAA,MACpB,iBAAmB,EAAA,KAAA;AAAA,MACnB,GAAG,OAAS,IAAA,IAAA,GAAA,KAAA,CAAA,GAAA,OAAA,CAAA,gBAAA;AAAA,MACZ,OAAS,EAAA,IAAA;AAAA,KACV,CAAA;AAAA,GACH,CAAA;AAMA,EAAA,MAAA,CAAO,GAAI,CAAA,CAAC,GAAc,EAAA,CAAA,EAAG,IAAS,KAAA;AACpC,IAAA,MAAM,aAAgB,GAAA,GAAA,CAAA;AACtB,IAAc,aAAA,CAAA,OAAA,GAAU,cAAc,aAAa,CAAA,CAAA;AACnD,IAAc,aAAA,CAAA,WAAA,GAAc,cAAc,iBAAiB,CAAA,CAAA;AAC3D,IAAA,OAAO,cAAc,aAAa,CAAA,CAAA;AAClC,IAAA,OAAO,cAAc,iBAAiB,CAAA,CAAA;AACtC,IAAK,IAAA,EAAA,CAAA;AAAA,GACN,CAAA,CAAA;AAGD,EAAO,MAAA,CAAA,GAAA,CAAI,2BAA2B,CAAA,CAAA;AAEtC,EAAO,OAAA,MAAA,CAAA;AACT;;;;;"}

package/dist/index.d.ts

@@ -1,7 +1,8 @@
 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';
+import { Router, RequestHandler } from 'express';
+import { middleware } from 'express-openapi-validator';
 
 /**
  * This file is meant to hold Immutable overwrites of the values provided by the `openapi3-ts`
@@ -279,11 +280,16 @@ type Filter<T, U> = T extends U ? T : never;
  */
 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];
 /**
+ * Helper to convert from string to number, used to index arrays and pull out just the indices in the array.
  * @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;
+type FromNumberStringToNumber<NumberString extends string | number | symbol> = NumberString extends `${infer R extends number}` ? R : never;
+/**
+ * @public
+ */
+type DocParameters<Doc extends RequiredDoc, Path extends Extract<keyof Doc['paths'], string>, Method extends keyof Doc['paths'][Path]> = {
+    [Index in keyof DocOperation<Doc, Path, Method>['parameters'] as FromNumberStringToNumber<Index>]: DocParameter<Doc, Path, Method, Index>;
+};
 /**
  * @public
  */
@@ -297,7 +303,7 @@ type MapToSchema<Doc extends RequiredDoc, T extends Record<string, ImmutablePara
 /**
  * @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;
+type ParametersSchema<Doc extends RequiredDoc, Path extends Extract<keyof Doc['paths'], string>, Method extends keyof Doc['paths'][Path], FilterType extends ImmutableParameterObject> = MapToSchema<Doc, FullMap<MapDiscriminatedUnion<Filter<ValueOf<DocParameters<Doc, Path, Method>>, FilterType>, 'name'>>>;
 /**
  * @public
  */
@@ -433,6 +439,7 @@ 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_FromNumberStringToNumber<NumberString extends string | number | symbol> = FromNumberStringToNumber<NumberString>;
 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_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>;
@@ -498,6 +505,7 @@ declare namespace index_d {
     index_d_ImmutablePathObject as ImmutablePathObject,
     index_d_ImmutableSchemaObject as ImmutableSchemaObject,
     index_d_DocParameter as DocParameter,
+    index_d_FromNumberStringToNumber as FromNumberStringToNumber,
     index_d_DocParameters as DocParameters,
     index_d_ParameterSchema as ParameterSchema,
     index_d_MapToSchema as MapToSchema,
@@ -530,4 +538,16 @@ interface ApiRouter<Doc extends RequiredDoc> extends Router {
     head: DocRequestMatcher<Doc, this, 'head'>;
 }
 
-export { ApiRouter, index_d as internal };
+/**
+ * Create a new OpenAPI router with some default middleware.
+ * @param spec - Your OpenAPI spec imported as a JSON object.
+ * @param validatorOptions - `openapi-express-validator` options to override the defaults.
+ * @returns A new express router with validation middleware.
+ * @public
+ */
+declare function createValidatedOpenApiRouter<T extends RequiredDoc>(spec: T, options?: {
+    validatorOptions?: Partial<Parameters<typeof middleware>['0']>;
+    middleware?: RequestHandler[];
+}): ApiRouter<T>;
+
+export { ApiRouter, createValidatedOpenApiRouter, index_d as internal };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@backstage/backend-openapi-utils",
   "description": "OpenAPI typescript support.",
-  "version": "0.0.2-next.1",
+  "version": "0.0.3-next.0",
   "main": "dist/index.cjs.js",
   "types": "dist/index.d.ts",
   "license": "Apache-2.0",
@@ -24,17 +24,21 @@
     "postpack": "backstage-cli package postpack"
   },
   "devDependencies": {
-    "@backstage/cli": "^0.22.7-next.0"
+    "@backstage/cli": "^0.22.10-next.0",
+    "supertest": "^6.1.3"
   },
   "files": [
     "dist"
   ],
   "dependencies": {
+    "@backstage/errors": "^1.2.1",
     "@types/express": "^4.17.6",
     "@types/express-serve-static-core": "^4.17.5",
     "express": "^4.17.1",
+    "express-openapi-validator": "^5.0.4",
     "express-promise-router": "^4.1.0",
     "json-schema-to-ts": "^2.6.2",
+    "lodash": "^4.17.21",
     "openapi3-ts": "^3.1.2"
   },
   "module": "dist/index.esm.js"