@backstage/plugin-catalog-backend-module-openapi 0.1.0 → 0.1.2-next.0

package/CHANGELOG.md

@@ -1,5 +1,52 @@
 # @backstage/plugin-catalog-backend-module-openapi
 
+## 0.1.2-next.0
+
+### Patch Changes
+
+- Updated dependencies
+  - @backstage/backend-common@0.15.1-next.0
+  - @backstage/plugin-catalog-backend@1.3.2-next.0
+  - @backstage/integration@1.3.1-next.0
+  - @backstage/plugin-catalog-node@1.0.2-next.0
+
+## 0.1.1
+
+### Patch Changes
+
+- b50e8e533b: Add an `$openapi` placeholder resolver that supports more use cases for resolving `$ref` instances. This means that the quite recently added `OpenApiRefProcessor` has been deprecated in favor of the `openApiPlaceholderResolver`.
+
+  An example of how to use it can be seen below.
+
+  ```yaml
+  apiVersion: backstage.io/v1alpha1
+  kind: API
+  metadata:
+    name: example
+    description: Example API
+  spec:
+    type: openapi
+    lifecycle: production
+    owner: team
+    definition:
+      $openapi: ./spec/openapi.yaml # by using $openapi Backstage will now resolve all $ref instances
+  ```
+
+- Updated dependencies
+  - @backstage/backend-common@0.15.0
+  - @backstage/plugin-catalog-node@1.0.1
+  - @backstage/integration@1.3.0
+  - @backstage/plugin-catalog-backend@1.3.1
+
+## 0.1.1-next.0
+
+### Patch Changes
+
+- Updated dependencies
+  - @backstage/backend-common@0.15.0-next.0
+  - @backstage/integration@1.3.0-next.0
+  - @backstage/plugin-catalog-backend@1.3.1-next.0
+
 ## 0.1.0
 
 ### Minor Changes

package/README.md

@@ -15,6 +15,32 @@ yarn add --cwd packages/backend @backstage/plugin-catalog-backend-module-openapi
 
 ### Adding the plugin to your `packages/backend`
 
+#### **openApiPlaceholderResolver**
+
+The placeholder resolver can be added by importing `openApiPlaceholderResolver` in `src/plugins/catalog.ts` in your `backend` package and adding the following.
+
+```ts
+builder.setPlaceholderResolver('openapi', openApiPlaceholderResolver);
+```
+
+This allows you to use the `$openapi` placeholder when referencing your OpenAPI specification. This will then resolve all `$ref` instances in your specification.
+
+```yaml
+apiVersion: backstage.io/v1alpha1
+kind: API
+metadata:
+  name: example
+  description: Example API
+spec:
+  type: openapi
+  lifecycle: production
+  owner: team
+  definition:
+    $openapi: ./spec/openapi.yaml # by using $openapi Backstage will now resolve all $ref instances
+```
+
+#### **OpenAPIRefProcessor** (deprecated)
+
 The processor can be added by importing `OpenApiRefProcessor` in `src/plugins/catalog.ts` in your `backend` package and adding the following.
 
 ```ts

package/dist/index.cjs.js

@@ -6,6 +6,7 @@ var integration = require('@backstage/integration');
 var SwaggerParser = require('@apidevtools/swagger-parser');
 var yaml = require('yaml');
 var path = require('path');
+var pluginCatalogNode = require('@backstage/plugin-catalog-node');
 
 function _interopDefaultLegacy (e) { return e && typeof e === 'object' && 'default' in e ? e : { 'default': e }; }
 
@@ -38,7 +39,7 @@ const getProtocol = (refPath) => {
   }
   return void 0;
 };
-async function bundleOpenApiSpecification(specification, targetUrl, reader, scmIntegration) {
+async function bundleOpenApiSpecification(specification, baseUrl, read, resolveUrl) {
   const fileUrlReaderResolver = {
     canRead: (file) => {
       const protocol = getProtocol(file.url);
@@ -46,20 +47,10 @@ async function bundleOpenApiSpecification(specification, targetUrl, reader, scmI
     },
     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");
+      const url = resolveUrl(relativePath, baseUrl);
+      return await read(url);
     }
   };
-  if (!specification) {
-    return void 0;
-  }
   const options = {
     resolve: {
       file: fileUrlReaderResolver,
@@ -88,17 +79,25 @@ class OpenApiRefProcessor {
     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) {
+    const definition = entity.spec.definition;
+    if (!scmIntegration || !definition) {
       return entity;
     }
+    const resolveUrl = (url, base) => {
+      return scmIntegration.resolveUrl({ url, base });
+    };
     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);
+      const bundledSpec = await bundleOpenApiSpecification(
+        definition.toString(),
+        location.target,
+        this.reader.read,
+        resolveUrl
+      );
       return {
         ...entity,
         spec: { ...entity.spec, definition: bundledSpec }
@@ -110,5 +109,53 @@ class OpenApiRefProcessor {
   }
 }
 
+async function openApiPlaceholderResolver(params) {
+  const { content, url } = await readTextLocation(params);
+  params.emit(pluginCatalogNode.processingResult.refresh(`url:${url}`));
+  try {
+    return await bundleOpenApiSpecification(
+      content,
+      url,
+      params.read,
+      params.resolveUrl
+    );
+  } catch (error) {
+    throw new Error(
+      `Placeholder $${params.key} unable to bundle OpenAPI specification at ${params.value}, ${error}`
+    );
+  }
+}
+async function readTextLocation(params) {
+  const newUrl = relativeUrl(params);
+  try {
+    const data = await params.read(newUrl);
+    return { content: data.toString("utf-8"), url: newUrl };
+  } catch (e) {
+    throw new Error(
+      `Placeholder $${params.key} could not read location ${params.value}, ${e}`
+    );
+  }
+}
+function relativeUrl({
+  key,
+  value,
+  baseUrl,
+  resolveUrl
+}) {
+  if (typeof value !== "string") {
+    throw new Error(
+      `Placeholder $${key} expected a string value parameter, in the form of an absolute URL or a relative path`
+    );
+  }
+  try {
+    return resolveUrl(value, baseUrl);
+  } catch (e) {
+    throw new Error(
+      `Placeholder $${key} could not form a URL out of ${baseUrl} and ${value}, ${e}`
+    );
+  }
+}
+
 exports.OpenApiRefProcessor = OpenApiRefProcessor;
+exports.openApiPlaceholderResolver = openApiPlaceholderResolver;
 //# sourceMappingURL=index.cjs.js.map

package/dist/index.cjs.js.map

@@ -1 +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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"}
+{"version":3,"file":"index.cjs.js","sources":["../src/lib/bundle.ts","../src/OpenApiRefProcessor.ts","../src/openApiPlaceholderResolver.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 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 type BundlerRead = (url: string) => Promise<Buffer>;\n\nexport type BundlerResolveUrl = (url: string, base: string) => string;\n\nexport async function bundleOpenApiSpecification(\n  specification: string,\n  baseUrl: string,\n  read: BundlerRead,\n  resolveUrl: BundlerResolveUrl,\n): Promise<string> {\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 = resolveUrl(relativePath, baseUrl);\n      return await read(url);\n    },\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/**\n * @public\n * @deprecated replaced by the openApiPlaceholderResolver\n */\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    const definition = entity.spec!.definition;\n\n    if (!scmIntegration || !definition) {\n      return entity;\n    }\n\n    const resolveUrl = (url: string, base: string): string => {\n      return scmIntegration.resolveUrl({ url, base });\n    };\n\n    this.logger.debug(`Bundling OpenAPI specification from ${location.target}`);\n    try {\n      const bundledSpec = await bundleOpenApiSpecification(\n        definition.toString(),\n        location.target,\n        this.reader.read,\n        resolveUrl,\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","/*\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 { PlaceholderResolverParams } from '@backstage/plugin-catalog-backend';\nimport { JsonValue } from '@backstage/types';\nimport { processingResult } from '@backstage/plugin-catalog-node';\nimport { bundleOpenApiSpecification } from './lib';\n\n/** @public */\nexport async function openApiPlaceholderResolver(\n  params: PlaceholderResolverParams,\n): Promise<JsonValue> {\n  const { content, url } = await readTextLocation(params);\n\n  params.emit(processingResult.refresh(`url:${url}`));\n\n  try {\n    return await bundleOpenApiSpecification(\n      content,\n      url,\n      params.read,\n      params.resolveUrl,\n    );\n  } catch (error) {\n    throw new Error(\n      `Placeholder \\$${params.key} unable to bundle OpenAPI specification at ${params.value}, ${error}`,\n    );\n  }\n}\n\n/*\n * Helpers, copied from PlaceholderProcessor\n */\n\nasync function readTextLocation(\n  params: PlaceholderResolverParams,\n): Promise<{ content: string; url: string }> {\n  const newUrl = relativeUrl(params);\n\n  try {\n    const data = await params.read(newUrl);\n    return { content: data.toString('utf-8'), url: newUrl };\n  } catch (e) {\n    throw new Error(\n      `Placeholder \\$${params.key} could not read location ${params.value}, ${e}`,\n    );\n  }\n}\n\nfunction relativeUrl({\n  key,\n  value,\n  baseUrl,\n  resolveUrl,\n}: PlaceholderResolverParams): string {\n  if (typeof value !== 'string') {\n    throw new Error(\n      `Placeholder \\$${key} expected a string value parameter, in the form of an absolute URL or a relative path`,\n    );\n  }\n\n  try {\n    return resolveUrl(value, baseUrl);\n  } catch (e) {\n    // The only remaining case that isn't support is a relative file path that should be\n    // resolved using a relative file location. Accessing local file paths can lead to\n    // path traversal attacks and access to any file on the host system. Implementing this\n    // would require additional security measures.\n    throw new Error(\n      `Placeholder \\$${key} could not form a URL out of ${baseUrl} and ${value}, ${e}`,\n    );\n  }\n}\n"],"names":["path","parse","SwaggerParser","stringify","ScmIntegrations","processingResult"],"mappings":"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"}

package/dist/index.d.ts

@@ -2,10 +2,14 @@ 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 { CatalogProcessor, LocationSpec, PlaceholderResolverParams } from '@backstage/plugin-catalog-backend';
 import { Logger } from 'winston';
+import { JsonValue } from '@backstage/types';
 
-/** @public */
+/**
+ * @public
+ * @deprecated replaced by the openApiPlaceholderResolver
+ */
 declare class OpenApiRefProcessor implements CatalogProcessor {
     private readonly integrations;
     private readonly logger;
@@ -23,4 +27,7 @@ declare class OpenApiRefProcessor implements CatalogProcessor {
     preProcessEntity(entity: Entity, location: LocationSpec): Promise<Entity>;
 }
 
-export { OpenApiRefProcessor };
+/** @public */
+declare function openApiPlaceholderResolver(params: PlaceholderResolverParams): Promise<JsonValue>;
+
+export { OpenApiRefProcessor, openApiPlaceholderResolver };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@backstage/plugin-catalog-backend-module-openapi",
   "description": "A Backstage catalog backend module that helps with OpenAPI specifications",
-  "version": "0.1.0",
+  "version": "0.1.2-next.0",
   "main": "dist/index.cjs.js",
   "types": "dist/index.d.ts",
   "license": "Apache-2.0",
@@ -34,21 +34,23 @@
   },
   "dependencies": {
     "@apidevtools/swagger-parser": "^10.1.0",
-    "@backstage/backend-common": "^0.14.1",
+    "@backstage/backend-common": "^0.15.1-next.0",
     "@backstage/catalog-model": "^1.1.0",
     "@backstage/config": "^1.0.1",
-    "@backstage/integration": "^1.2.2",
-    "@backstage/plugin-catalog-backend": "^1.3.0",
+    "@backstage/integration": "^1.3.1-next.0",
+    "@backstage/plugin-catalog-backend": "^1.3.2-next.0",
+    "@backstage/plugin-catalog-node": "^1.0.2-next.0",
+    "@backstage/types": "^1.0.0",
     "winston": "^3.2.1",
     "yaml": "^2.1.1"
   },
   "devDependencies": {
-    "@backstage/backend-test-utils": "^0.1.26",
-    "@backstage/cli": "^0.18.0",
+    "@backstage/backend-test-utils": "^0.1.28-next.0",
+    "@backstage/cli": "^0.18.2-next.0",
     "openapi-types": "^12.0.0"
   },
   "files": [
     "dist"
   ],
-  "gitHead": "999878d8f1ae30f6a15925816af2016cb9d717a1"
+  "gitHead": "c6c0b1978a7ab4d29d813996c56beb7e6b48a268"
 }