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

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # @backstage/backend-openapi-utils
 
+## 0.6.7-next.1
+
+### Patch Changes
+
+- Updated dependencies
+  - @backstage/backend-plugin-api@1.8.0-next.1
+
 ## 0.6.7-next.0
 
 ### Patch Changes

package/README.md

@@ -4,6 +4,8 @@
 
 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.
 
+Only supports OpenAPI 3.1 specifications.
+
 ## Getting Started
 
 ### Configuration

package/dist/index.d.ts

@@ -618,6 +618,7 @@ interface TypedRouter<GeneratedEndpointMap extends EndpointMap> extends Router {
 declare function getOpenApiSpecRoute(baseUrl: string): string;
 /**
  * Create a new OpenAPI router with some default middleware.
+ * Only supports OpenAPI 3.1 specifications.
  * @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.
@@ -629,6 +630,7 @@ declare function createValidatedOpenApiRouter<T extends RequiredDoc>(spec: T, op
 }): ApiRouter<typeof spec>;
 /**
  * Create a new OpenAPI router with some default middleware.
+ * Only supports OpenAPI 3.1 specifications.
  * @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.

package/dist/stub.cjs.js.map

@@ -1 +1 @@
-{"version":3,"file":"stub.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, TypedRouter } from './router';\nimport { EndpointMap, RequiredDoc } from './types';\nimport {\n  ErrorRequestHandler,\n  RequestHandler,\n  NextFunction,\n  Request,\n  Response,\n  json,\n  Router,\n} from 'express';\nimport { InputError } from '@backstage/errors';\nimport { middleware as OpenApiValidator } from 'express-openapi-validator';\nimport { OPENAPI_SPEC_ROUTE } from './constants';\nimport { isErrorResult, merge } from 'openapi-merge';\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 * Given a base url for a plugin, find the given OpenAPI spec for that plugin.\n * @param baseUrl - Plugin base url.\n * @returns OpenAPI spec route for the base url.\n * @public\n */\nexport function getOpenApiSpecRoute(baseUrl: string) {\n  return `${baseUrl}${OPENAPI_SPEC_ROUTE}`;\n}\n\n/**\n * Create a router with validation middleware. This is used by typing methods to create an\n *  \"OpenAPI router\" with all of the expected validation + metadata.\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 */\nfunction createRouterWithValidation(\n  spec: RequiredDoc,\n  options?: {\n    validatorOptions?: Partial<Parameters<typeof OpenApiValidator>['0']>;\n    middleware?: RequestHandler[];\n  },\n): Router {\n  const router = PromiseRouter();\n  router.use(options?.middleware || getDefaultRouterMiddleware());\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      useRequestUrl: true,\n      ignoreUndocumented: true,\n      validateResponses: false,\n      ...options?.validatorOptions,\n      apiSpec: spec as any,\n    }),\n  );\n\n  // Any errors from the middleware get through here.\n  router.use(validatorErrorTransformer());\n\n  router.get(OPENAPI_SPEC_ROUTE, async (req, res) => {\n    const mergeOutput = merge([\n      {\n        oas: spec as any,\n        pathModification: {\n          /**\n           * Get the route that this OpenAPI spec is hosted on. The other\n           *  approach of using the discovery API increases the router constructor\n           *  significantly and since we're just looking for path and not full URL,\n           *  this works.\n           *\n           * If we wanted to add a list of servers, there may be a case for adding\n           *  discovery API to get an exhaustive list of upstream servers, but that's\n           *  also not currently supported.\n           */\n          prepend: req.originalUrl.replace(OPENAPI_SPEC_ROUTE, ''),\n        },\n      },\n    ]);\n    if (isErrorResult(mergeOutput)) {\n      throw new InputError('Invalid spec defined');\n    }\n    res.json(mergeOutput.output);\n  });\n  return router;\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  return createRouterWithValidation(spec, options) as ApiRouter<typeof spec>;\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 createValidatedOpenApiRouterFromGeneratedEndpointMap<\n  T extends EndpointMap,\n>(\n  spec: RequiredDoc,\n  options?: {\n    validatorOptions?: Partial<Parameters<typeof OpenApiValidator>['0']>;\n    middleware?: RequestHandler[];\n  },\n) {\n  return createRouterWithValidation(spec, options) as TypedRouter<T>;\n}\n"],"names":["InputError","json","OPENAPI_SPEC_ROUTE","PromiseRouter","OpenApiValidator","merge","isErrorResult"],"mappings":";;;;;;;;;;;;;AAiCA,SAAS,yBAAA,GAAiD;AACxD,EAAA,OAAO,CAAC,KAAA,EAAc,CAAA,EAAY,EAAA,EAAc,IAAA,KAAuB;AACrE,IAAA,IAAA,CAAK,IAAIA,iBAAA,CAAW,KAAA,CAAM,OAAO,CAAC,CAAA;AAAA,EACpC,CAAA;AACF;AAEO,SAAS,0BAAA,GAA6B;AAC3C,EAAA,OAAO,CAACC,cAAM,CAAA;AAChB;AAQO,SAAS,oBAAoB,OAAA,EAAiB;AACnD,EAAA,OAAO,CAAA,EAAG,OAAO,CAAA,EAAGC,4BAAkB,CAAA,CAAA;AACxC;AASA,SAAS,0BAAA,CACP,MACA,OAAA,EAIQ;AACR,EAAA,MAAM,SAASC,8BAAA,EAAc;AAC7B,EAAA,MAAA,CAAO,GAAA,CAAI,OAAA,EAAS,UAAA,IAAc,0BAAA,EAA4B,CAAA;AAG9D,EAAA,MAAA,CAAO,GAAA;AAAA,IACLC,kCAAA,CAAiB;AAAA,MACf,gBAAA,EAAkB;AAAA,QAChB,WAAA,EAAa,KAAA;AAAA,QACb,2BAAA,EAA6B;AAAA,OAC/B;AAAA,MACA,aAAA,EAAe,IAAA;AAAA,MACf,kBAAA,EAAoB,IAAA;AAAA,MACpB,iBAAA,EAAmB,KAAA;AAAA,MACnB,GAAG,OAAA,EAAS,gBAAA;AAAA,MACZ,OAAA,EAAS;AAAA,KACV;AAAA,GACH;AAGA,EAAA,MAAA,CAAO,GAAA,CAAI,2BAA2B,CAAA;AAEtC,EAAA,MAAA,CAAO,GAAA,CAAIF,4BAAA,EAAoB,OAAO,GAAA,EAAK,GAAA,KAAQ;AACjD,IAAA,MAAM,cAAcG,kBAAA,CAAM;AAAA,MACxB;AAAA,QACE,GAAA,EAAK,IAAA;AAAA,QACL,gBAAA,EAAkB;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,UAWhB,OAAA,EAAS,GAAA,CAAI,WAAA,CAAY,OAAA,CAAQH,8BAAoB,EAAE;AAAA;AACzD;AACF,KACD,CAAA;AACD,IAAA,IAAII,0BAAA,CAAc,WAAW,CAAA,EAAG;AAC9B,MAAA,MAAM,IAAIN,kBAAW,sBAAsB,CAAA;AAAA,IAC7C;AACA,IAAA,GAAA,CAAI,IAAA,CAAK,YAAY,MAAM,CAAA;AAAA,EAC7B,CAAC,CAAA;AACD,EAAA,OAAO,MAAA;AACT;AASO,SAAS,4BAAA,CACd,MACA,OAAA,EAIA;AACA,EAAA,OAAO,0BAAA,CAA2B,MAAM,OAAO,CAAA;AACjD;AASO,SAAS,oDAAA,CAGd,MACA,OAAA,EAIA;AACA,EAAA,OAAO,0BAAA,CAA2B,MAAM,OAAO,CAAA;AACjD;;;;;;;"}
+{"version":3,"file":"stub.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, TypedRouter } from './router';\nimport { EndpointMap, RequiredDoc } from './types';\nimport {\n  ErrorRequestHandler,\n  RequestHandler,\n  NextFunction,\n  Request,\n  Response,\n  json,\n  Router,\n} from 'express';\nimport { InputError } from '@backstage/errors';\nimport { middleware as OpenApiValidator } from 'express-openapi-validator';\nimport { OPENAPI_SPEC_ROUTE } from './constants';\nimport { isErrorResult, merge } from 'openapi-merge';\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 * Given a base url for a plugin, find the given OpenAPI spec for that plugin.\n * @param baseUrl - Plugin base url.\n * @returns OpenAPI spec route for the base url.\n * @public\n */\nexport function getOpenApiSpecRoute(baseUrl: string) {\n  return `${baseUrl}${OPENAPI_SPEC_ROUTE}`;\n}\n\n/**\n * Create a router with validation middleware. This is used by typing methods to create an\n *  \"OpenAPI router\" with all of the expected validation + metadata.\n * Only supports OpenAPI 3.1 specifications.\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 */\nfunction createRouterWithValidation(\n  spec: RequiredDoc,\n  options?: {\n    validatorOptions?: Partial<Parameters<typeof OpenApiValidator>['0']>;\n    middleware?: RequestHandler[];\n  },\n): Router {\n  const router = PromiseRouter();\n  router.use(options?.middleware || getDefaultRouterMiddleware());\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      useRequestUrl: true,\n      ignoreUndocumented: true,\n      validateResponses: false,\n      ...options?.validatorOptions,\n      apiSpec: spec as any,\n    }),\n  );\n\n  // Any errors from the middleware get through here.\n  router.use(validatorErrorTransformer());\n\n  router.get(OPENAPI_SPEC_ROUTE, async (req, res) => {\n    const mergeOutput = merge([\n      {\n        oas: spec as any,\n        pathModification: {\n          /**\n           * Get the route that this OpenAPI spec is hosted on. The other\n           *  approach of using the discovery API increases the router constructor\n           *  significantly and since we're just looking for path and not full URL,\n           *  this works.\n           *\n           * If we wanted to add a list of servers, there may be a case for adding\n           *  discovery API to get an exhaustive list of upstream servers, but that's\n           *  also not currently supported.\n           */\n          prepend: req.originalUrl.replace(OPENAPI_SPEC_ROUTE, ''),\n        },\n      },\n    ]);\n    if (isErrorResult(mergeOutput)) {\n      throw new InputError('Invalid spec defined');\n    }\n    res.json(mergeOutput.output);\n  });\n  return router;\n}\n\n/**\n * Create a new OpenAPI router with some default middleware.\n * Only supports OpenAPI 3.1 specifications.\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  return createRouterWithValidation(spec, options) as ApiRouter<typeof spec>;\n}\n\n/**\n * Create a new OpenAPI router with some default middleware.\n * Only supports OpenAPI 3.1 specifications.\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 createValidatedOpenApiRouterFromGeneratedEndpointMap<\n  T extends EndpointMap,\n>(\n  spec: RequiredDoc,\n  options?: {\n    validatorOptions?: Partial<Parameters<typeof OpenApiValidator>['0']>;\n    middleware?: RequestHandler[];\n  },\n) {\n  return createRouterWithValidation(spec, options) as TypedRouter<T>;\n}\n"],"names":["InputError","json","OPENAPI_SPEC_ROUTE","PromiseRouter","OpenApiValidator","merge","isErrorResult"],"mappings":";;;;;;;;;;;;;AAiCA,SAAS,yBAAA,GAAiD;AACxD,EAAA,OAAO,CAAC,KAAA,EAAc,CAAA,EAAY,EAAA,EAAc,IAAA,KAAuB;AACrE,IAAA,IAAA,CAAK,IAAIA,iBAAA,CAAW,KAAA,CAAM,OAAO,CAAC,CAAA;AAAA,EACpC,CAAA;AACF;AAEO,SAAS,0BAAA,GAA6B;AAC3C,EAAA,OAAO,CAACC,cAAM,CAAA;AAChB;AAQO,SAAS,oBAAoB,OAAA,EAAiB;AACnD,EAAA,OAAO,CAAA,EAAG,OAAO,CAAA,EAAGC,4BAAkB,CAAA,CAAA;AACxC;AAUA,SAAS,0BAAA,CACP,MACA,OAAA,EAIQ;AACR,EAAA,MAAM,SAASC,8BAAA,EAAc;AAC7B,EAAA,MAAA,CAAO,GAAA,CAAI,OAAA,EAAS,UAAA,IAAc,0BAAA,EAA4B,CAAA;AAG9D,EAAA,MAAA,CAAO,GAAA;AAAA,IACLC,kCAAA,CAAiB;AAAA,MACf,gBAAA,EAAkB;AAAA,QAChB,WAAA,EAAa,KAAA;AAAA,QACb,2BAAA,EAA6B;AAAA,OAC/B;AAAA,MACA,aAAA,EAAe,IAAA;AAAA,MACf,kBAAA,EAAoB,IAAA;AAAA,MACpB,iBAAA,EAAmB,KAAA;AAAA,MACnB,GAAG,OAAA,EAAS,gBAAA;AAAA,MACZ,OAAA,EAAS;AAAA,KACV;AAAA,GACH;AAGA,EAAA,MAAA,CAAO,GAAA,CAAI,2BAA2B,CAAA;AAEtC,EAAA,MAAA,CAAO,GAAA,CAAIF,4BAAA,EAAoB,OAAO,GAAA,EAAK,GAAA,KAAQ;AACjD,IAAA,MAAM,cAAcG,kBAAA,CAAM;AAAA,MACxB;AAAA,QACE,GAAA,EAAK,IAAA;AAAA,QACL,gBAAA,EAAkB;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,UAWhB,OAAA,EAAS,GAAA,CAAI,WAAA,CAAY,OAAA,CAAQH,8BAAoB,EAAE;AAAA;AACzD;AACF,KACD,CAAA;AACD,IAAA,IAAII,0BAAA,CAAc,WAAW,CAAA,EAAG;AAC9B,MAAA,MAAM,IAAIN,kBAAW,sBAAsB,CAAA;AAAA,IAC7C;AACA,IAAA,GAAA,CAAI,IAAA,CAAK,YAAY,MAAM,CAAA;AAAA,EAC7B,CAAC,CAAA;AACD,EAAA,OAAO,MAAA;AACT;AAUO,SAAS,4BAAA,CACd,MACA,OAAA,EAIA;AACA,EAAA,OAAO,0BAAA,CAA2B,MAAM,OAAO,CAAA;AACjD;AAUO,SAAS,oDAAA,CAGd,MACA,OAAA,EAIA;AACA,EAAA,OAAO,0BAAA,CAA2B,MAAM,OAAO,CAAA;AACjD;;;;;;;"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@backstage/backend-openapi-utils",
-  "version": "0.6.7-next.0",
+  "version": "0.6.7-next.1",
   "description": "OpenAPI typescript support.",
   "backstage": {
     "role": "node-library"
@@ -54,7 +54,7 @@
   },
   "dependencies": {
     "@apidevtools/swagger-parser": "^10.1.0",
-    "@backstage/backend-plugin-api": "1.7.1-next.0",
+    "@backstage/backend-plugin-api": "1.8.0-next.1",
     "@backstage/errors": "1.2.7",
     "@backstage/types": "1.2.2",
     "@types/express": "^4.17.6",
@@ -71,7 +71,7 @@
     "openapi3-ts": "^3.1.2"
   },
   "devDependencies": {
-    "@backstage/cli": "0.35.5-next.0",
+    "@backstage/cli": "0.36.0-next.2",
     "@backstage/test-utils": "1.7.16-next.0",
     "msw": "^1.0.0",
     "supertest": "^7.0.0"