@backstage/backend-openapi-utils 0.0.5 → 0.1.0-next.0

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # @backstage/backend-openapi-utils
 
+## 0.1.0-next.0
+
+### Minor Changes
+
+- 785fb1ea75: Adds a new route, `/openapi.json` to validated routers for displaying their full OpenAPI spec in a standard endpoint.
+
+### Patch Changes
+
+- 6694b369a3: Adds a new function `wrapInOpenApiTestServer` that allows for proxied requests at runtime. This will support the new `yarn backstage-repo-tools schema openapi test` command.
+- Updated dependencies
+  - @backstage/backend-plugin-api@0.6.7-next.0
+  - @backstage/config@1.1.1
+  - @backstage/errors@1.2.3
+
 ## 0.0.5
 
 ### Patch Changes

package/README.md

@@ -65,7 +65,7 @@ export function createRouter() {
 
 ### Why am I getting `unknown` as the type for a response?
 
-This can happen when you have a `charset` defined in your `response.content` section. Something like `response.content[    'application/json; charset=utf-8:']` will cause this issue.
+This can happen when you have a `charset` defined in your `response.content` section. Something like `response.content['application/json; charset=utf-8:']` will cause this issue.
 
 ## INTERNAL
 

package/dist/index.cjs.js

@@ -6,6 +6,7 @@ var PromiseRouter = require('express-promise-router');
 var express = require('express');
 var errors = require('@backstage/errors');
 var expressOpenapiValidator = require('express-openapi-validator');
+var openapiMerge = require('openapi-merge');
 
 function _interopDefaultLegacy (e) { return e && typeof e === 'object' && 'default' in e ? e : { 'default': e }; }
 
@@ -15,6 +16,8 @@ var index = /*#__PURE__*/Object.freeze({
   __proto__: null
 });
 
+const OPENAPI_SPEC_ROUTE = "/openapi.json";
+
 const baseUrlSymbol = Symbol();
 const originalUrlSymbol = Symbol();
 function validatorErrorTransformer() {
@@ -25,6 +28,9 @@ function validatorErrorTransformer() {
 function getDefaultRouterMiddleware() {
   return [express.json()];
 }
+function getOpenApiSpecRoute(baseUrl) {
+  return `${baseUrl}${OPENAPI_SPEC_ROUTE}`;
+}
 function createValidatedOpenApiRouter(spec, options) {
   const router = PromiseRouter__default["default"]();
   router.use((options == null ? void 0 : options.middleware) || getDefaultRouterMiddleware());
@@ -57,9 +63,46 @@ function createValidatedOpenApiRouter(spec, options) {
     next();
   });
   router.use(validatorErrorTransformer());
+  router.get(OPENAPI_SPEC_ROUTE, async (req, res) => {
+    const mergeOutput = openapiMerge.merge([
+      {
+        oas: spec,
+        pathModification: {
+          /**
+           * Get the route that this OpenAPI spec is hosted on. The other
+           *  approach of using the discovery API increases the router constructor
+           *  significantly and since we're just looking for path and not full URL,
+           *  this works.
+           *
+           * If we wanted to add a list of servers, there may be a case for adding
+           *  discovery API to get an exhaustive list of upstream servers, but that's
+           *  also not currently supported.
+           */
+          prepend: req.originalUrl.replace(OPENAPI_SPEC_ROUTE, "")
+        }
+      }
+    ]);
+    if (openapiMerge.isErrorResult(mergeOutput)) {
+      throw new errors.InputError("Invalid spec defined");
+    }
+    res.json(mergeOutput.output);
+  });
   return router;
 }
 
+const wrapInOpenApiTestServer = (app) => {
+  if (process.env.OPTIC_PROXY) {
+    const server = app.listen(+process.env.PORT);
+    return {
+      ...server,
+      address: () => new URL(process.env.OPTIC_PROXY)
+    };
+  }
+  return app;
+};
+
 exports.createValidatedOpenApiRouter = createValidatedOpenApiRouter;
+exports.getOpenApiSpecRoute = getOpenApiSpecRoute;
 exports.internal = index;
+exports.wrapInOpenApiTestServer = wrapInOpenApiTestServer;
 //# sourceMappingURL=index.cjs.js.map

package/dist/index.cjs.js.map

@@ -1 +1 @@
-{"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;;;;;"}
+{"version":3,"file":"index.cjs.js","sources":["../src/constants.ts","../src/stub.ts","../src/testUtils.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\n/**\n * The route that all OpenAPI specs should be served from.\n * @public\n */\nexport const OPENAPI_SPEC_ROUTE = '/openapi.json';\n","/*\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';\nimport { OPENAPI_SPEC_ROUTE } from './constants';\nimport { isErrorResult, merge } from 'openapi-merge';\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 * 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 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();\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  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\n  return router as ApiRouter<typeof spec>;\n}\n","/*\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 */\nimport { Express } from 'express';\nimport { Server } from 'http';\n\n/**\n * !!! THIS CURRENTLY ONLY SUPPORTS SUPERTEST !!!\n * Running against supertest, we need some way to hit the optic proxy. This ensures that\n *  that happens at runtime when in the context of a `yarn optic capture` command.\n * @param app - Express router that would be passed to supertest's `request`.\n * @returns A wrapper around the express router (or the router untouched) that still works with supertest.\n * @public\n */\nexport const wrapInOpenApiTestServer = (app: Express): Server | Express => {\n  if (process.env.OPTIC_PROXY) {\n    const server = app.listen(+process.env.PORT!);\n    return {\n      ...server,\n      address: () => new URL(process.env.OPTIC_PROXY!),\n    } as any;\n  }\n  return app;\n};\n"],"names":["InputError","json","PromiseRouter","OpenApiValidator","merge","isErrorResult"],"mappings":";;;;;;;;;;;;;;;;;;AAoBO,MAAM,kBAAqB,GAAA,eAAA;;ACgBlC,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;AAQO,SAAS,oBAAoB,OAAiB,EAAA;AACnD,EAAO,OAAA,CAAA,EAAG,OAAO,CAAA,EAAG,kBAAkB,CAAA,CAAA,CAAA;AACxC,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,EAAA,MAAA,CAAO,GAAI,CAAA,kBAAA,EAAoB,OAAO,GAAA,EAAK,GAAQ,KAAA;AACjD,IAAA,MAAM,cAAcC,kBAAM,CAAA;AAAA,MACxB;AAAA,QACE,GAAK,EAAA,IAAA;AAAA,QACL,gBAAkB,EAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,UAWhB,OAAS,EAAA,GAAA,CAAI,WAAY,CAAA,OAAA,CAAQ,oBAAoB,EAAE,CAAA;AAAA,SACzD;AAAA,OACF;AAAA,KACD,CAAA,CAAA;AACD,IAAI,IAAAC,0BAAA,CAAc,WAAW,CAAG,EAAA;AAC9B,MAAM,MAAA,IAAIL,kBAAW,sBAAsB,CAAA,CAAA;AAAA,KAC7C;AACA,IAAI,GAAA,CAAA,IAAA,CAAK,YAAY,MAAM,CAAA,CAAA;AAAA,GAC5B,CAAA,CAAA;AAED,EAAO,OAAA,MAAA,CAAA;AACT;;AClIa,MAAA,uBAAA,GAA0B,CAAC,GAAmC,KAAA;AACzE,EAAI,IAAA,OAAA,CAAQ,IAAI,WAAa,EAAA;AAC3B,IAAA,MAAM,SAAS,GAAI,CAAA,MAAA,CAAO,CAAC,OAAA,CAAQ,IAAI,IAAK,CAAA,CAAA;AAC5C,IAAO,OAAA;AAAA,MACL,GAAG,MAAA;AAAA,MACH,SAAS,MAAM,IAAI,GAAI,CAAA,OAAA,CAAQ,IAAI,WAAY,CAAA;AAAA,KACjD,CAAA;AAAA,GACF;AACA,EAAO,OAAA,GAAA,CAAA;AACT;;;;;;;"}

package/dist/index.d.ts

@@ -1,8 +1,9 @@
 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, RequestHandler } from 'express';
+import { Router, RequestHandler, Express } from 'express';
 import { middleware } from 'express-openapi-validator';
+import { Server } from 'http';
 
 /**
  * This file is meant to hold Immutable overwrites of the values provided by the `openapi3-ts`
@@ -576,6 +577,13 @@ interface ApiRouter<Doc extends RequiredDoc> extends Router {
     head: DocRequestMatcher<Doc, this, 'head'>;
 }
 
+/**
+ * Given a base url for a plugin, find the given OpenAPI spec for that plugin.
+ * @param baseUrl - Plugin base url.
+ * @returns OpenAPI spec route for the base url.
+ * @public
+ */
+declare function getOpenApiSpecRoute(baseUrl: string): string;
 /**
  * Create a new OpenAPI router with some default middleware.
  * @param spec - Your OpenAPI spec imported as a JSON object.
@@ -588,4 +596,14 @@ declare function createValidatedOpenApiRouter<T extends RequiredDoc>(spec: T, op
     middleware?: RequestHandler[];
 }): ApiRouter<T>;
 
-export { ApiRouter, CookieParameters, HeaderParameters, PathParameters, QueryParameters, Request, Response, createValidatedOpenApiRouter, index_d as internal };
+/**
+ * !!! THIS CURRENTLY ONLY SUPPORTS SUPERTEST !!!
+ * Running against supertest, we need some way to hit the optic proxy. This ensures that
+ *  that happens at runtime when in the context of a `yarn optic capture` command.
+ * @param app - Express router that would be passed to supertest's `request`.
+ * @returns A wrapper around the express router (or the router untouched) that still works with supertest.
+ * @public
+ */
+declare const wrapInOpenApiTestServer: (app: Express) => Server | Express;
+
+export { ApiRouter, CookieParameters, HeaderParameters, PathParameters, QueryParameters, Request, Response, createValidatedOpenApiRouter, getOpenApiSpecRoute, index_d as internal, wrapInOpenApiTestServer };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@backstage/backend-openapi-utils",
   "description": "OpenAPI typescript support.",
-  "version": "0.0.5",
+  "version": "0.1.0-next.0",
   "main": "dist/index.cjs.js",
   "types": "dist/index.d.ts",
   "license": "Apache-2.0",
@@ -30,13 +30,15 @@
     "postpack": "backstage-cli package postpack"
   },
   "devDependencies": {
-    "@backstage/cli": "^0.23.0",
+    "@backstage/cli": "^0.24.0-next.0",
     "supertest": "^6.1.3"
   },
   "files": [
     "dist"
   ],
   "dependencies": {
+    "@backstage/backend-plugin-api": "^0.6.7-next.0",
+    "@backstage/config": "^1.1.1",
     "@backstage/errors": "^1.2.3",
     "@types/express": "^4.17.6",
     "@types/express-serve-static-core": "^4.17.5",
@@ -45,6 +47,7 @@
     "express-promise-router": "^4.1.0",
     "json-schema-to-ts": "^2.6.2",
     "lodash": "^4.17.21",
+    "openapi-merge": "^1.3.2",
     "openapi3-ts": "^3.1.2"
   },
   "module": "dist/index.esm.js"