@backstage/plugin-catalog-backend-module-openapi 0.0.0-nightly-20220624024747

package/CHANGELOG.md

@@ -0,0 +1,17 @@
+# @backstage/plugin-catalog-backend-module-openapi
+
+## 0.0.0-nightly-20220624024747
+
+### Minor Changes
+
+- 67503d159e: Add basic OpenAPI \$ref support.
+
+  For more information see [here](https://github.com/backstage/backstage/tree/master/plugins/catalog-backend-module-openapi).
+
+### Patch Changes
+
+- Updated dependencies
+  - @backstage/backend-common@0.0.0-nightly-20220624024747
+  - @backstage/catalog-model@0.0.0-nightly-20220624024747
+  - @backstage/plugin-catalog-backend@0.0.0-nightly-20220624024747
+  - @backstage/integration@0.0.0-nightly-20220624024747

package/README.md

@@ -0,0 +1,27 @@
+# Catalog Backend Module for OpenAPI specifications
+
+This is an extension module to the plugin-catalog-backend plugin, providing extensions targeted at OpenAPI specifications.
+
+With this you can split your OpenAPI definition into multiple files and reference them. They will be bundled, using an UrlReader, during processing and stored as a single specification.
+
+## Installation
+
+### Install the package
+
+```bash
+# From your Backstage root directory
+yarn add --cwd packages/backend @backstage/plugin-catalog-backend-module-openapi
+```
+
+### Adding the plugin to your `packages/backend`
+
+The processor can be added by importing `OpenApiRefProcessor` in `src/plugins/catalog.ts` in your `backend` package and adding the following.
+
+```ts
+builder.addProcessor(
+  OpenApiRefProcessor.fromConfig(env.config, {
+    logger: env.logger,
+    reader: env.reader,
+  }),
+);
+```

package/dist/index.cjs.js

@@ -0,0 +1,114 @@
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+var integration = require('@backstage/integration');
+var SwaggerParser = require('@apidevtools/swagger-parser');
+var yaml = require('yaml');
+var path = require('path');
+
+function _interopDefaultLegacy (e) { return e && typeof e === 'object' && 'default' in e ? e : { 'default': e }; }
+
+function _interopNamespace(e) {
+  if (e && e.__esModule) return e;
+  var n = Object.create(null);
+  if (e) {
+    Object.keys(e).forEach(function (k) {
+      if (k !== 'default') {
+        var d = Object.getOwnPropertyDescriptor(e, k);
+        Object.defineProperty(n, k, d.get ? d : {
+          enumerable: true,
+          get: function () { return e[k]; }
+        });
+      }
+    });
+  }
+  n["default"] = e;
+  return Object.freeze(n);
+}
+
+var SwaggerParser__default = /*#__PURE__*/_interopDefaultLegacy(SwaggerParser);
+var path__namespace = /*#__PURE__*/_interopNamespace(path);
+
+const protocolPattern = /^(\w{2,}):\/\//i;
+const getProtocol = (refPath) => {
+  const match = protocolPattern.exec(refPath);
+  if (match) {
+    return match[1].toLowerCase();
+  }
+  return void 0;
+};
+async function bundleOpenApiSpecification(specification, targetUrl, reader, scmIntegration) {
+  const fileUrlReaderResolver = {
+    canRead: (file) => {
+      const protocol = getProtocol(file.url);
+      return protocol === void 0 || protocol === "file";
+    },
+    read: async (file) => {
+      const relativePath = path__namespace.relative(".", file.url);
+      const url = scmIntegration.resolveUrl({
+        base: targetUrl,
+        url: relativePath
+      });
+      if (reader.readUrl) {
+        const data = await reader.readUrl(url);
+        return data.buffer();
+      }
+      throw new Error("UrlReader has no readUrl method defined");
+    }
+  };
+  if (!specification) {
+    return void 0;
+  }
+  const options = {
+    resolve: {
+      file: fileUrlReaderResolver,
+      http: true
+    }
+  };
+  const specObject = yaml.parse(specification);
+  const bundledSpec = await SwaggerParser__default["default"].bundle(specObject, options);
+  return yaml.stringify(bundledSpec);
+}
+
+class OpenApiRefProcessor {
+  static fromConfig(config, options) {
+    const integrations = integration.ScmIntegrations.fromConfig(config);
+    return new OpenApiRefProcessor({
+      ...options,
+      integrations
+    });
+  }
+  constructor(options) {
+    this.integrations = options.integrations;
+    this.logger = options.logger;
+    this.reader = options.reader;
+  }
+  getProcessorName() {
+    return "OpenApiRefProcessor";
+  }
+  async preProcessEntity(entity, location) {
+    var _a;
+    if (!entity || entity.kind !== "API" || entity.spec && entity.spec.type !== "openapi") {
+      return entity;
+    }
+    const scmIntegration = this.integrations.byUrl(location.target);
+    if (!scmIntegration) {
+      return entity;
+    }
+    this.logger.debug(`Bundling OpenAPI specification from ${location.target}`);
+    try {
+      const bundledSpec = await bundleOpenApiSpecification((_a = entity.spec.definition) == null ? void 0 : _a.toString(), location.target, this.reader, scmIntegration);
+      return {
+        ...entity,
+        spec: { ...entity.spec, definition: bundledSpec }
+      };
+    } catch (error) {
+      this.logger.error(`Unable to bundle OpenAPI specification`, error);
+      return entity;
+    }
+  }
+}
+
+exports.OpenApiRefProcessor = OpenApiRefProcessor;
+//# sourceMappingURL=index.cjs.js.map

package/dist/index.cjs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.cjs.js","sources":["../src/lib/bundle.ts","../src/OpenApiRefProcessor.ts"],"sourcesContent":["/*\n * Copyright 2020 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 { UrlReader } from '@backstage/backend-common';\nimport { ScmIntegration } from '@backstage/integration';\nimport SwaggerParser from '@apidevtools/swagger-parser';\nimport { parse, stringify } from 'yaml';\nimport * as path from 'path';\n\nconst protocolPattern = /^(\\w{2,}):\\/\\//i;\nconst getProtocol = (refPath: string) => {\n  const match = protocolPattern.exec(refPath);\n  if (match) {\n    return match[1].toLowerCase();\n  }\n  return undefined;\n};\n\nexport async function bundleOpenApiSpecification(\n  specification: string | undefined,\n  targetUrl: string,\n  reader: UrlReader,\n  scmIntegration: ScmIntegration,\n): Promise<string | undefined> {\n  const fileUrlReaderResolver: SwaggerParser.ResolverOptions = {\n    canRead: file => {\n      const protocol = getProtocol(file.url);\n      return protocol === undefined || protocol === 'file';\n    },\n    read: async file => {\n      const relativePath = path.relative('.', file.url);\n      const url = scmIntegration.resolveUrl({\n        base: targetUrl,\n        url: relativePath,\n      });\n      if (reader.readUrl) {\n        const data = await reader.readUrl(url);\n        return data.buffer();\n      }\n      throw new Error('UrlReader has no readUrl method defined');\n    },\n  };\n\n  if (!specification) {\n    return undefined;\n  }\n\n  const options: SwaggerParser.Options = {\n    resolve: {\n      file: fileUrlReaderResolver,\n      http: true,\n    },\n  };\n  const specObject = parse(specification);\n  const bundledSpec = await SwaggerParser.bundle(specObject, options);\n  return stringify(bundledSpec);\n}\n","/*\n * Copyright 2020 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 { UrlReader } from '@backstage/backend-common';\nimport { Entity } from '@backstage/catalog-model';\nimport { Config } from '@backstage/config';\nimport { ScmIntegrations } from '@backstage/integration';\nimport {\n  CatalogProcessor,\n  LocationSpec,\n} from '@backstage/plugin-catalog-backend';\nimport { bundleOpenApiSpecification } from './lib';\nimport { Logger } from 'winston';\n\n/** @public */\nexport class OpenApiRefProcessor implements CatalogProcessor {\n  private readonly integrations: ScmIntegrations;\n  private readonly logger: Logger;\n  private readonly reader: UrlReader;\n\n  static fromConfig(\n    config: Config,\n    options: { logger: Logger; reader: UrlReader },\n  ) {\n    const integrations = ScmIntegrations.fromConfig(config);\n\n    return new OpenApiRefProcessor({\n      ...options,\n      integrations,\n    });\n  }\n\n  constructor(options: {\n    integrations: ScmIntegrations;\n    logger: Logger;\n    reader: UrlReader;\n  }) {\n    this.integrations = options.integrations;\n    this.logger = options.logger;\n    this.reader = options.reader;\n  }\n\n  getProcessorName(): string {\n    return 'OpenApiRefProcessor';\n  }\n\n  async preProcessEntity(\n    entity: Entity,\n    location: LocationSpec,\n  ): Promise<Entity> {\n    if (\n      !entity ||\n      entity.kind !== 'API' ||\n      (entity.spec && entity.spec.type !== 'openapi')\n    ) {\n      return entity;\n    }\n\n    const scmIntegration = this.integrations.byUrl(location.target);\n    if (!scmIntegration) {\n      return entity;\n    }\n\n    this.logger.debug(`Bundling OpenAPI specification from ${location.target}`);\n    try {\n      const bundledSpec = await bundleOpenApiSpecification(\n        entity.spec!.definition?.toString(),\n        location.target,\n        this.reader,\n        scmIntegration,\n      );\n\n      return {\n        ...entity,\n        spec: { ...entity.spec, definition: bundledSpec },\n      };\n    } catch (error) {\n      this.logger.error(`Unable to bundle OpenAPI specification`, error);\n      return entity;\n    }\n  }\n}\n"],"names":["path","parse","SwaggerParser","stringify","ScmIntegrations"],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,26 @@
+import { UrlReader } from '@backstage/backend-common';
+import { Entity } from '@backstage/catalog-model';
+import { Config } from '@backstage/config';
+import { ScmIntegrations } from '@backstage/integration';
+import { CatalogProcessor, LocationSpec } from '@backstage/plugin-catalog-backend';
+import { Logger } from 'winston';
+
+/** @public */
+declare class OpenApiRefProcessor implements CatalogProcessor {
+    private readonly integrations;
+    private readonly logger;
+    private readonly reader;
+    static fromConfig(config: Config, options: {
+        logger: Logger;
+        reader: UrlReader;
+    }): OpenApiRefProcessor;
+    constructor(options: {
+        integrations: ScmIntegrations;
+        logger: Logger;
+        reader: UrlReader;
+    });
+    getProcessorName(): string;
+    preProcessEntity(entity: Entity, location: LocationSpec): Promise<Entity>;
+}
+
+export { OpenApiRefProcessor };

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@backstage/plugin-catalog-backend-module-openapi",
+  "description": "A Backstage catalog backend module that helps with OpenAPI specifications",
+  "version": "0.0.0-nightly-20220624024747",
+  "main": "dist/index.cjs.js",
+  "types": "dist/index.d.ts",
+  "license": "Apache-2.0",
+  "private": false,
+  "publishConfig": {
+    "access": "public",
+    "main": "dist/index.cjs.js",
+    "types": "dist/index.d.ts"
+  },
+  "backstage": {
+    "role": "backend-plugin-module"
+  },
+  "homepage": "https://backstage.io",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/backstage/backstage",
+    "directory": "plugins/catalog-backend-module-openapi"
+  },
+  "keywords": [
+    "backstage"
+  ],
+  "scripts": {
+    "build": "backstage-cli package build",
+    "lint": "backstage-cli package lint",
+    "test": "backstage-cli package test",
+    "prepack": "backstage-cli package prepack",
+    "postpack": "backstage-cli package postpack",
+    "clean": "backstage-cli package clean",
+    "start": "backstage-cli package start"
+  },
+  "dependencies": {
+    "@apidevtools/swagger-parser": "^10.1.0",
+    "@backstage/backend-common": "^0.0.0-nightly-20220624024747",
+    "@backstage/catalog-model": "^0.0.0-nightly-20220624024747",
+    "@backstage/config": "^1.0.1",
+    "@backstage/integration": "^0.0.0-nightly-20220624024747",
+    "@backstage/plugin-catalog-backend": "^0.0.0-nightly-20220624024747",
+    "winston": "^3.2.1",
+    "yaml": "^2.1.1"
+  },
+  "devDependencies": {
+    "@backstage/backend-test-utils": "^0.0.0-nightly-20220624024747",
+    "@backstage/cli": "^0.0.0-nightly-20220624024747",
+    "openapi-types": "^11.0.1"
+  },
+  "files": [
+    "dist"
+  ]
+}