feat(actionsRegistry): Adding support for examples (#33551)

* feat(backend-plugin-api): add typed examples to actions registry

Signed-off-by: benjdlambert <ben@blam.sh>

* fix: address review feedback for actions registry examples

Signed-off-by: benjdlambert <ben@blam.sh>

* fix: remove empty examples from scaffolder action bridge

Signed-off-by: benjdlambert <ben@blam.sh>

* chore: add changeset for scaffolder-backend

Signed-off-by: benjdlambert <ben@blam.sh>

* fix: update router test to match removed examples field

Signed-off-by: benjdlambert <ben@blam.sh>

---------

Signed-off-by: benjdlambert <ben@blam.sh>

packages/backend-plugin-api/report-alpha.api.md

@@ -20,6 +20,17 @@ export type ActionsRegistryActionContext<TInputSchema extends AnyZodObject> = {
   credentials: BackstageCredentials;
 };
 
+// @alpha
+export type ActionsRegistryActionExample<
+  TInputSchema extends AnyZodObject,
+  TOutputSchema extends AnyZodObject,
+> = {
+  title: string;
+  description?: string;
+  input: z.infer<TInputSchema>;
+  output?: z.infer<TOutputSchema>;
+};
+
 // @alpha (undocumented)
 export type ActionsRegistryActionOptions<
   TInputSchema extends AnyZodObject,
@@ -32,6 +43,7 @@ export type ActionsRegistryActionOptions<
     input: (zod: typeof z) => TInputSchema;
     output: (zod: typeof z) => TOutputSchema;
   };
+  examples?: Array<ActionsRegistryActionExample<TInputSchema, TOutputSchema>>;
   visibilityPermission?: BasicPermission;
   attributes?: {
     destructive?: boolean;
@@ -92,6 +104,12 @@ export type ActionsServiceAction = {
     input: JSONSchema7;
     output: JSONSchema7;
   };
+  examples?: Array<{
+    title: string;
+    description?: string;
+    input: JsonObject;
+    output?: JsonObject;
+  }>;
   attributes: {
     readOnly: boolean;
     destructive: boolean;

packages/backend-plugin-api/src/alpha/ActionsRegistryService.ts

@@ -29,6 +29,21 @@ export type ActionsRegistryActionContext<TInputSchema extends AnyZodObject> = {
   credentials: BackstageCredentials;
 };
 
+/**
+ * An example of how to use an action registered in the actions registry.
+ *
+ * @alpha
+ */
+export type ActionsRegistryActionExample<
+  TInputSchema extends AnyZodObject,
+  TOutputSchema extends AnyZodObject,
+> = {
+  title: string;
+  description?: string;
+  input: z.infer<TInputSchema>;
+  output?: z.infer<TOutputSchema>;
+};
+
 /**
  * @alpha
  */
@@ -43,6 +58,7 @@ export type ActionsRegistryActionOptions<
     input: (zod: typeof z) => TInputSchema;
     output: (zod: typeof z) => TOutputSchema;
   };
+  examples?: Array<ActionsRegistryActionExample<TInputSchema, TOutputSchema>>;
   visibilityPermission?: BasicPermission;
   attributes?: {
     destructive?: boolean;

packages/backend-plugin-api/src/alpha/ActionsService.ts

@@ -30,6 +30,12 @@ export type ActionsServiceAction = {
     input: JSONSchema7;
     output: JSONSchema7;
   };
+  examples?: Array<{
+    title: string;
+    description?: string;
+    input: JsonObject;
+    output?: JsonObject;
+  }>;
   attributes: {
     readOnly: boolean;
     destructive: boolean;

packages/backend-plugin-api/src/alpha/index.ts

@@ -23,6 +23,7 @@ export type {
   ActionsRegistryService,
   ActionsRegistryActionOptions,
   ActionsRegistryActionContext,
+  ActionsRegistryActionExample,
 } from './ActionsRegistryService';
 
 export type { ActionsService, ActionsServiceAction } from './ActionsService';

packages/backend-plugin-api/src/services/definitions/ActionsRegistryService.ts

@@ -27,6 +27,21 @@ export type ActionsRegistryActionContext<TInputSchema extends AnyZodObject> = {
   credentials: BackstageCredentials;
 };
 
+/**
+ * An example of how to use an action registered in the actions registry.
+ *
+ * @public
+ */
+export type ActionsRegistryActionExample<
+  TInputSchema extends AnyZodObject,
+  TOutputSchema extends AnyZodObject,
+> = {
+  title: string;
+  description?: string;
+  input: z.infer<TInputSchema>;
+  output?: z.infer<TOutputSchema>;
+};
+
 /**
  * @public
  */
@@ -41,6 +56,7 @@ export type ActionsRegistryActionOptions<
     input: (zod: typeof z) => TInputSchema;
     output: (zod: typeof z) => TOutputSchema;
   };
+  examples?: Array<ActionsRegistryActionExample<TInputSchema, TOutputSchema>>;
   visibilityPermission?: BasicPermission;
   attributes?: {
     destructive?: boolean;

packages/backend-plugin-api/src/services/definitions/ActionsService.ts

@@ -29,6 +29,12 @@ export type ActionsServiceAction = {
     input: JSONSchema7;
     output: JSONSchema7;
   };
+  examples?: Array<{
+    title: string;
+    description?: string;
+    input: JsonObject;
+    output?: JsonObject;
+  }>;
   attributes: {
     readOnly: boolean;
     destructive: boolean;