Updated scaffolder-common api-reports

Signed-off-by: Harry Hogg <hhogg@spotify.com>

plugins/scaffolder-common/api-report.md

@@ -8,8 +8,15 @@ import type { EntityMeta } from '@backstage/catalog-model';
 import { JsonObject } from '@backstage/types';
 import type { JsonValue } from '@backstage/types';
 import { KindValidator } from '@backstage/catalog-model';
+import { ResourcePermission } from '@backstage/plugin-permission-common';
 import type { UserEntity } from '@backstage/catalog-model';
 
+// @alpha
+export const RESOURCE_TYPE_SCAFFOLDER_TEMPLATE = 'scaffolder-template';
+
+// @alpha
+export const scaffolderPermissions: ResourcePermission<'scaffolder-template'>[];
+
 // @public
 export const isTemplateEntityV1beta3: (
   entity: Entity,
@@ -42,20 +49,30 @@ export interface TaskStep {
   name: string;
 }
 
+// @public
+export interface TemplateEntityStepV1beta3 extends JsonObject {
+  // (undocumented)
+  'backstage:accessControl'?: TemplateSpecValuesMetadata;
+  // (undocumented)
+  action: string;
+  // (undocumented)
+  id?: string;
+  // (undocumented)
+  if?: string | boolean;
+  // (undocumented)
+  input?: JsonObject;
+  // (undocumented)
+  name?: string;
+}
+
 // @public
 export interface TemplateEntityV1beta3 extends Entity {
   apiVersion: 'scaffolder.backstage.io/v1beta3';
   kind: 'Template';
   spec: {
     type: string;
-    parameters?: JsonObject | JsonObject[];
-    steps: Array<{
-      id?: string;
-      name?: string;
-      action: string;
-      input?: JsonObject;
-      if?: string | boolean;
-    }>;
+    parameters?: TemplateParameter | TemplateParameter[];
+    steps: Array<TemplateEntityStepV1beta3>;
     output?: {
       [name: string]: string;
     };
@@ -74,4 +91,26 @@ export type TemplateInfo = {
     metadata: EntityMeta;
   };
 };
+
+// @public
+export interface TemplateParameter extends JsonObject {
+  // (undocumented)
+  'backstage:accessControl'?: TemplateSpecValuesMetadata;
+  // (undocumented)
+  properties?: {
+    [name: string]: JsonObject;
+  };
+}
+
+// @alpha
+export const templateParameterReadPermission: ResourcePermission<'scaffolder-template'>;
+
+// @public
+export interface TemplateSpecValuesMetadata extends JsonObject {
+  // (undocumented)
+  tags?: string[];
+}
+
+// @alpha
+export const templateStepReadPermission: ResourcePermission<'scaffolder-template'>;
 ```

plugins/scaffolder-common/src/TemplateEntityV1beta3.ts

@@ -68,7 +68,9 @@ export interface TemplateEntityV1beta3 extends Entity {
 }
 
 /**
- * TODO
+ * Step that is part of a Template Entity.
+ *
+ * @public
  */
 export interface TemplateEntityStepV1beta3 extends JsonObject {
   id?: string;
@@ -80,20 +82,24 @@ export interface TemplateEntityStepV1beta3 extends JsonObject {
 }
 
 /**
- * TODO
- */
-export interface TemplateAccessControl extends JsonObject {
-  tags?: string[];
-}
-
-/**
- * TODO
+ * Parameter that is part of a Template Entity.
+ *
+ * @public
  */
 export interface TemplateParameter extends JsonObject {
   'backstage:accessControl'?: TemplateAccessControl;
   properties?: { [name: string]: JsonObject };
 }
 
+/**
+ *  Access control properties for parts of a template.
+ *
+ * @public
+ */
+export interface TemplateAccessControl extends JsonObject {
+  tags?: string[];
+}
+
 const validator = entityKindSchemaValidator(schema);
 
 /**

plugins/scaffolder-common/src/permissions.ts

@@ -16,8 +16,23 @@
 
 import { createPermission } from '@backstage/plugin-permission-common';
 
+/**
+ * Permission resource type which corresponds to a scaffolder templates.
+ *
+ * @alpha
+ */
 export const RESOURCE_TYPE_SCAFFOLDER_TEMPLATE = 'scaffolder-template';
 
+/**
+ * This permission is used to authorize actions that involve reading
+ * one or more parameters from a template.
+ *
+ * If this permission is not authorized, it will appear that the
+ * parameter does not exist in the template — both in the frontend
+ * and in API responses.
+ *
+ * @alpha
+ */
 export const templateParameterReadPermission = createPermission({
   name: 'scaffolder.template.parameter.read',
   attributes: {
@@ -26,6 +41,16 @@ export const templateParameterReadPermission = createPermission({
   resourceType: RESOURCE_TYPE_SCAFFOLDER_TEMPLATE,
 });
 
+/**
+ * This permission is used to authorize actions that involve reading
+ * one or more steps from a template.
+ *
+ * If this permission is not authorized, it will appear that the
+ * step does not exist in the template — both in the frontend
+ * and in API responses. Steps will also not be executed.
+ *
+ * @alpha
+ */
 export const templateStepReadPermission = createPermission({
   name: 'scaffolder.template.step.read',
   attributes: {
@@ -34,6 +59,10 @@ export const templateStepReadPermission = createPermission({
   resourceType: RESOURCE_TYPE_SCAFFOLDER_TEMPLATE,
 });
 
+/**
+ * List of all the scaffolder permissions
+ * @alpha
+ */
 export const scaffolderPermissions = [
   templateParameterReadPermission,
   templateStepReadPermission,