chore: fix api-report and documentation for scaffolder-common

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

plugins/scaffolder-common/api-report.md

@@ -13,41 +13,28 @@ export type TaskSpec = TaskSpecV1beta3;
 
 // @public
 export interface TaskSpecV1beta3 {
-  // (undocumented)
   apiVersion: 'scaffolder.backstage.io/v1beta3';
-  // (undocumented)
   output: {
     [name: string]: JsonValue;
   };
-  // (undocumented)
   parameters: JsonObject;
-  // (undocumented)
   steps: TaskStep[];
-  // (undocumented)
   templateInfo?: TemplateInfo;
 }
 
 // @public
 export interface TaskStep {
-  // (undocumented)
   action: string;
-  // (undocumented)
   id: string;
-  // (undocumented)
   if?: string | boolean;
-  // (undocumented)
   input?: JsonObject;
-  // (undocumented)
   name: string;
 }
 
 // @public
 export interface TemplateEntityV1beta3 extends Entity {
-  // (undocumented)
   apiVersion: 'scaffolder.backstage.io/v1beta3';
-  // (undocumented)
   kind: 'Template';
-  // (undocumented)
   spec: {
     type: string;
     parameters?: JsonObject | JsonObject[];

plugins/scaffolder-common/src/TaskSpec.ts

@@ -23,7 +23,13 @@ import { JsonValue, JsonObject } from '@backstage/types';
  * @public
  */
 export type TemplateInfo = {
+  /**
+   * The entityRef of the template
+   */
   entityRef: string;
+  /**
+   * Where the template is stored, so we can resolve relative paths for things like `fetch:template` paths.
+   */
   baseUrl?: string;
 };
 
@@ -33,10 +39,25 @@ export type TemplateInfo = {
  * @public
  */
 export interface TaskStep {
+  /**
+   * A unqiue identifier for this step.
+   */
   id: string;
+  /**
+   * A display name to show the user.
+   */
   name: string;
+  /**
+   * The underlying action ID that will be called part of running this step.
+   */
   action: string;
+  /**
+   * Additional data that will be passed to the action.
+   */
   input?: JsonObject;
+  /**
+   * When this is false, or if the templated value string evaluates to something that is false the step will be skipped.
+   */
   if?: string | boolean;
 }
 
@@ -47,10 +68,28 @@ export interface TaskStep {
  * @public
  */
 export interface TaskSpecV1beta3 {
+  /**
+   * The apiVersion string of the TaskSpec.
+   */
   apiVersion: 'scaffolder.backstage.io/v1beta3';
+  /**
+   * This is a JSONSchema or an array of JSONSchema's which is used to render a form in the frontend
+   * to collect user input and validate it against that schema. This can then be used in the `steps` part below to template
+   * variables passed from the user into each action in the template.
+   */
   parameters: JsonObject;
+  /**
+   * A list of steps to be executed in sequence which are defined by the template. These steps are a list of the underlying
+   * javascript action and some optional input parameters that may or may not have been collected from the end user.
+   */
   steps: TaskStep[];
+  /**
+   * The output is an object where template authors can pull out information from template actions and return them in a known standard way.
+   */
   output: { [name: string]: JsonValue };
+  /**
+   * Some information about the template that is stored on the task spec.
+   */
   templateInfo?: TemplateInfo;
 }
 

plugins/scaffolder-common/src/TemplateEntityV1beta3.ts

@@ -29,11 +29,32 @@ import schema from './Template.v1beta3.schema.json';
  * @public
  */
 export interface TemplateEntityV1beta3 extends Entity {
+  /**
+   * The apiVersion string of the TaskSpec.
+   */
   apiVersion: 'scaffolder.backstage.io/v1beta3';
+  /**
+   * The kind of the entity
+   */
   kind: 'Template';
+  /**
+   * The specification of the Template Entity
+   */
   spec: {
+    /**
+     * The type that the Template will create. For example service, website or library.
+     */
     type: string;
+    /**
+     * This is a JSONSchema or an array of JSONSchema's which is used to render a form in the frontend
+     * to collect user input and validate it against that schema. This can then be used in the `steps` part below to template
+     * variables passed from the user into each action in the template.
+     */
     parameters?: JsonObject | JsonObject[];
+    /**
+     * A list of steps to be executed in sequence which are defined by the template. These steps are a list of the underlying
+     * javascript action and some optional input parameters that may or may not have been collected from the end user.
+     */
     steps: Array<{
       id?: string;
       name?: string;
@@ -41,7 +62,13 @@ export interface TemplateEntityV1beta3 extends Entity {
       input?: JsonObject;
       if?: string | boolean;
     }>;
+    /**
+     * The output is an object where template authors can pull out information from template actions and return them in a known standard way.
+     */
     output?: { [name: string]: string };
+    /**
+     * The owner of the TemplateEntity
+     */
     owner?: string;
   };
 }