paulononato/backstage
1
0
Fork 0
Code Issues Pull Requests Actions 43 Packages Projects Releases Wiki Activity

add examples of scaffolder action inputs to docs

Browse Source 
Signed-off-by: Brian Fletcher <brian@roadie.io>
This commit is contained in:
Brian Fletcher
2022-12-20 16:05:24 +00:00
parent 3e14ea6b47
commit b44eb68bcb
12 changed files with 184 additions and 14 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.changeset/.changeset/rude-gifts-pay.md
+5
View File
@@ -0,0 +1,5 @@
---
'@backstage/plugin-scaffolder': patch
---
Show action example yaml on the scaffolder actions documentation page.
.changeset/metal-nails-punch.md
+5
View File
@@ -0,0 +1,5 @@
---
'@backstage/plugin-scaffolder-backend': patch
---
Changes to provide examples alongside scaffolder task actions.
plugins/scaffolder-backend/api-report.md
+4
View File
@@ -843,6 +843,10 @@ export class TaskWorker {
export type TemplateAction<Input extends JsonObject> = {
id: string;
description?: string;
examples?: {
description: string;
example: string;
}[];
supportsDryRun?: boolean;
schema?: {
input?: Schema;
plugins/scaffolder-backend/src/scaffolder/actions/builtin/catalog/register.ts
+24 -1
View File
@@ -19,6 +19,28 @@ import { ScmIntegrations } from '@backstage/integration';
import { CatalogApi } from '@backstage/catalog-client';
import { stringifyEntityRef } from '@backstage/catalog-model';
import { createTemplateAction } from '../../createTemplateAction';
import yaml from 'yaml';
const id = 'catalog:register';
const examples = [
{
description: 'Register With the catalog',
example: yaml.stringify({
steps: [
{
action: id,
id: 'register-with-catalog',
name: 'Register with the catalog',
input: {
catalogInfoUrl:
'http://github.com/backstage/backstage/blob/master/catalog-info.yaml',
},
},
],
}),
},
];
/**
* Registers entities from a catalog descriptor file in the workspace into the software catalog.
@@ -34,9 +56,10 @@ export function createCatalogRegisterAction(options: {
| { catalogInfoUrl: string; optional?: boolean }
| { repoContentsUrl: string; catalogInfoPath?: string; optional?: boolean }
>({
id: 'catalog:register',
id,
description:
'Registers entities from a catalog descriptor file in the workspace into the software catalog.',
examples,
schema: {
input: {
oneOf: [
plugins/scaffolder-backend/src/scaffolder/actions/builtin/catalog/write.ts
+34 -1
View File
@@ -20,14 +20,47 @@ import * as yaml from 'yaml';
import { Entity } from '@backstage/catalog-model';
import { resolveSafeChildPath } from '@backstage/backend-common';
const id = 'catalog:write';
const examples = [
{
description: 'Write a catalog yaml file',
example: yaml.stringify({
steps: [
{
action: id,
id: 'create-catalog-info-file',
name: 'Create catalog file',
input: {
entity: {
apiVersion: 'backstage.io/v1alpha1',
kind: 'Component',
metadata: {
name: 'test',
annotations: {},
},
spec: {
type: 'service',
lifecycle: 'production',
owner: 'default/owner',
},
},
},
},
],
}),
},
];
/**
* Writes a catalog descriptor file containing the provided entity to a path in the workspace.
* @public
*/
export function createCatalogWriteAction() {
return createTemplateAction<{ filePath?: string; entity: Entity }>({
id: 'catalog:write',
id,
description: 'Writes the catalog-info.yaml for your template',
examples,
schema: {
input: {
type: 'object',
plugins/scaffolder-backend/src/scaffolder/actions/builtin/debug/log.ts
+23 -1
View File
@@ -17,6 +17,27 @@
import { readdir, stat } from 'fs-extra';
import { relative, join } from 'path';
import { createTemplateAction } from '../../createTemplateAction';
import yaml from 'yaml';
const id = 'debug:log';
const examples = [
{
description: 'Write a debug message',
example: yaml.stringify({
steps: [
{
action: id,
id: 'write-debug-line',
name: 'Write log line',
input: {
message: 'Hello, there',
},
},
],
}),
},
];
/**
* Writes a message into the log or lists all files in the workspace
@@ -30,9 +51,10 @@ import { createTemplateAction } from '../../createTemplateAction';
*/
export function createDebugLogAction() {
return createTemplateAction<{ message?: string; listWorkspace?: boolean }>({
id: 'debug:log',
id,
description:
'Writes a message into the log or lists all files in the workspace.',
examples,
schema: {
input: {
type: 'object',
plugins/scaffolder-backend/src/scaffolder/actions/types.ts
+1
View File
@@ -66,6 +66,7 @@ export type ActionContext<Input extends JsonObject> = {
export type TemplateAction<Input extends JsonObject> = {
id: string;
description?: string;
examples?: { description: string; example: string }[];
supportsDryRun?: boolean;
schema?: {
input?: Schema;
plugins/scaffolder-backend/src/service/router.ts
+1
View File
@@ -292,6 +292,7 @@ export async function createRouter(
return {
id: action.id,
description: action.description,
examples: action.examples,
schema: action.schema,
};
});
plugins/scaffolder/api-report.md
+18 -8
View File
@@ -38,6 +38,23 @@ import { UIOptionsType } from '@rjsf/utils';
import { UiSchema } from '@rjsf/utils';
import { z } from 'zod';
// @public
export type Action = {
id: string;
description?: string;
schema?: {
input?: JSONSchema7;
output?: JSONSchema7;
};
examples?: ActionExample[];
};
// @public
export type ActionExample = {
description: string;
example: string;
};
// @alpha
export function createNextScaffolderFieldExtension<
TReturnValue = unknown,
@@ -188,14 +205,7 @@ export interface LayoutOptions<P = any> {
export type LayoutTemplate<T = any> = FormProps_2<T>['ObjectFieldTemplate'];
// @public
export type ListActionsResponse = Array<{
id: string;
description?: string;
schema?: {
input?: JSONSchema7;
output?: JSONSchema7;
};
}>;
export type ListActionsResponse = Array<Action>;
// @public
export type LogEvent = {
plugins/scaffolder/src/components/ActionsPage/ActionsPage.tsx
+46
View File
@@ -27,6 +27,7 @@ import {
TableContainer,
TableHead,
TableRow,
Grid,
makeStyles,
} from '@material-ui/core';
import { JSONSchema7, JSONSchema7Definition } from 'json-schema';
@@ -39,7 +40,11 @@ import {
Header,
Page,
ErrorPage,
Table as BackstageTable,
TableColumn,
CodeSnippet,
} from '@backstage/core-components';
import { ActionExample } from '../../types';
const useStyles = makeStyles(theme => ({
code: {
@@ -67,6 +72,29 @@ const useStyles = makeStyles(theme => ({
},
}));
const examplesColumns: TableColumn<ActionExample>[] = [
{
title: 'Description',
field: 'description',
width: '20%',
},
{
title: 'Example',
render: ({ example }) => {
return (
<Grid>
<CodeSnippet
text={example}
showLineNumbers
showCopyCodeButton
language="JavaScript"
/>
</Grid>
);
},
},
];
export const ActionsPage = () => {
const api = useApi(scaffolderApiRef);
const classes = useStyles();
@@ -180,6 +208,24 @@ export const ActionsPage = () => {
{renderTable(action.schema.output)}
</Box>
)}
{action.examples && (
<Box pb={2}>
<Typography variant="h5">Examples</Typography>
<BackstageTable
data={action.examples}
columns={examplesColumns}
options={{
search: false,
showTitle: false,
toolbar: false,
loadingType: 'linear',
header: true,
padding: 'dense',
paging: false,
}}
/>
</Box>
)}
</Box>
);
});
plugins/scaffolder/src/index.ts
+2
View File
@@ -22,6 +22,8 @@
export { scaffolderApiRef, ScaffolderClient } from './api';
export type {
Action,
ActionExample,
ListActionsResponse,
LogEvent,
ScaffolderApi,
plugins/scaffolder/src/types.ts
+21 -3
View File
@@ -43,18 +43,36 @@ export type ScaffolderTask = {
};
/**
* The response shape for the `listActions` call to the `scaffolder-backend`
* A single action example
*
* @public
*/
export type ListActionsResponse = Array<{
export type ActionExample = {
description: string;
example: string;
};
/**
* The response shape for a single action in the `listActions` call to the `scaffolder-backend`
*
* @public
*/
export type Action = {
id: string;
description?: string;
schema?: {
input?: JSONSchema7;
output?: JSONSchema7;
};
}>;
examples?: ActionExample[];
};
/**
* The response shape for the `listActions` call to the `scaffolder-backend`
*
* @public
*/
export type ListActionsResponse = Array<Action>;
/** @public */
export type ScaffolderOutputLink = {