feat: remove the backstage.io/definition-at-location annotation

The annotation was superseded by the placeholder processor.

.changeset/2803.md

@@ -0,0 +1,26 @@
+---
+'@backstage/plugin-catalog-backend': minor
+---
+
+Remove the backstage.io/definition-at-location annotation.
+The annotation was superseded by the placeholder processor.
+
+```yaml
+apiVersion: backstage.io/v1alpha1
+kind: API
+metadata:
+  name: spotify
+  description: The Spotify web API
+  tags:
+    - spotify
+    - rest
+  annotations:
+    # Don't use this annotation, but the placeholder $text instead (see below).
+    backstage.io/definition-at-location: 'url:https://raw.githubusercontent.com/APIs-guru/openapi-directory/master/APIs/spotify.com/v1/swagger.yaml'
+spec:
+  type: openapi
+  lifecycle: production
+  owner: spotify@example.com
+  definition:
+    $text: https://raw.githubusercontent.com/APIs-guru/openapi-directory/master/APIs/spotify.com/v1/swagger.yaml
+```

docs/features/software-catalog/well-known-annotations.md

@@ -41,27 +41,6 @@ expecting a two-item array out of it. The format of the target part is
 type-dependent and could conceivably even be an empty string, but the separator
 colon is always present.
 
-### backstage.io/definition-at-location
-
-```yaml
-# Example
-apiVersion: backstage.io/v1alpha1
-kind: API
-metadata:
-  name: petstore
-  annotations:
-    backstage.io/definition-at-location: 'url:https://petstore.swagger.io/v2/swagger.json'
-spec:
-  type: openapi
-```
-
-This annotation allows to fetch an API definition from another location, instead
-of wrapping the API definition inside the definition field. This allows to
-easily consume existing API definition. The definition is fetched during
-ingestion by a processor and included in the entity. It is updated on every
-refresh. The annotation contains a location reference string that contains the
-location processor type and the target.
-
 ### backstage.io/techdocs-ref
 
 ```yaml
@@ -205,6 +184,25 @@ This annotation was used for a while to enable the GitHub Actions feature. This
 is now instead using the [github.com/project-slug](#github-com-project-slug)
 annotation, with the same value format.
 
+### backstage.io/definition-at-location
+
+This annotation allowed to load the API definition from another location. Now
+placeholders can be used instead:
+
+```
+apiVersion: backstage.io/v1alpha1
+kind: API
+metadata:
+  name: petstore
+  description: The Petstore API
+spec:
+  type: openapi
+  lifecycle: production
+  owner: petstore@example.com
+  definition:
+    $text: https://petstore.swagger.io/v2/swagger.json
+```
+
 ## Links
 
 - [Descriptor Format: annotations](descriptor-format.md#annotations-optional)

plugins/catalog-backend/src/ingestion/LocationReaders.ts

@@ -26,7 +26,6 @@ import { Config, ConfigReader } from '@backstage/config';
 import { Logger } from 'winston';
 import { CatalogRulesEnforcer } from './CatalogRules';
 import { AnnotateLocationEntityProcessor } from './processors/AnnotateLocationEntityProcessor';
-import { ApiDefinitionAtLocationProcessor } from './processors/ApiDefinitionAtLocationProcessor';
 import { AzureApiReaderProcessor } from './processors/AzureApiReaderProcessor';
 import { BitbucketApiReaderProcessor } from './processors/BitbucketApiReaderProcessor';
 import { CodeOwnersProcessor } from './processors/CodeOwnersProcessor';
@@ -127,7 +126,6 @@ export class LocationReaders implements LocationReader {
       new YamlProcessor(),
       PlaceholderProcessor.default(),
       new CodeOwnersProcessor(),
-      new ApiDefinitionAtLocationProcessor(),
       new EntityPolicyProcessor(entityPolicy),
       new LocationRefProcessor(),
       new AnnotateLocationEntityProcessor(),

plugins/catalog-backend/src/ingestion/processors/index.ts

@@ -20,7 +20,6 @@ export { results };
 export * from './types';
 
 export { AnnotateLocationEntityProcessor } from './AnnotateLocationEntityProcessor';
-export { ApiDefinitionAtLocationProcessor } from './ApiDefinitionAtLocationProcessor';
 export { AzureApiReaderProcessor } from './AzureApiReaderProcessor';
 export { BitbucketApiReaderProcessor } from './BitbucketApiReaderProcessor';
 export { CodeOwnersProcessor } from './CodeOwnersProcessor';