From fcc206cfc7727e4585c5ec9884ceb44645c7f284 Mon Sep 17 00:00:00 2001 From: Patrik Oldsberg Date: Sat, 4 Sep 2021 17:41:36 +0200 Subject: [PATCH 1/3] plugins/todo: fix warnings in api-reports Signed-off-by: Patrik Oldsberg --- plugins/todo/api-report.md | 82 ++++++++++++++++++++++++++---- plugins/todo/src/api/TodoClient.ts | 14 ++++- plugins/todo/src/api/index.ts | 9 +++- plugins/todo/src/api/types.ts | 46 +++++++++++++++-- plugins/todo/src/index.ts | 10 +++- plugins/todo/src/plugin.ts | 12 ++++- 6 files changed, 154 insertions(+), 19 deletions(-) diff --git a/plugins/todo/api-report.md b/plugins/todo/api-report.md index 548d55accb..22fca3cb9e 100644 --- a/plugins/todo/api-report.md +++ b/plugins/todo/api-report.md @@ -7,22 +7,84 @@ import { ApiRef } from '@backstage/core-plugin-api'; import { BackstagePlugin } from '@backstage/core-plugin-api'; +import { DiscoveryApi } from '@backstage/core-plugin-api'; import { Entity } from '@backstage/catalog-model'; +import { IdentityApi } from '@backstage/core-plugin-api'; -// Warning: (ae-missing-release-tag) "EntityTodoContent" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// -// @public (undocumented) +// @public export const EntityTodoContent: () => JSX.Element; -// Warning: (ae-forgotten-export) The symbol "TodoApi" needs to be exported by the entry point index.d.ts -// Warning: (ae-missing-release-tag) "todoApiRef" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// -// @public (undocumented) +// @public +export interface TodoApi { + listTodos(options: TodoListOptions): Promise; +} + +// @public export const todoApiRef: ApiRef; -// Warning: (ae-missing-release-tag) "todoPlugin" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// -// @public (undocumented) +// @public +export class TodoClient implements TodoApi { + constructor(options: TodoClientOptions); + // (undocumented) + listTodos({ + entity, + offset, + limit, + orderBy, + filters, + }: TodoListOptions): Promise; +} + +// @public +export interface TodoClientOptions { + // (undocumented) + discoveryApi: DiscoveryApi; + // (undocumented) + identityApi: IdentityApi; +} + +// @public +export type TodoItem = { + text: string; + tag: string; + author?: string; + viewUrl?: string; + lineNumber?: number; + repoFilePath?: string; +}; + +// @public +export type TodoListFields = + | 'text' + | 'tag' + | 'author' + | 'viewUrl' + | 'repoFilePath'; + +// @public +export type TodoListOptions = { + entity?: Entity; + offset?: number; + limit?: number; + orderBy?: { + field: TodoListFields; + direction: 'asc' | 'desc'; + }; + filters?: { + field: TodoListFields; + value: string; + }[]; +}; + +// @public +export type TodoListResult = { + items: TodoItem[]; + totalCount: number; + offset: number; + limit: number; +}; + +// @public export const todoPlugin: BackstagePlugin<{}, {}>; // (No @packageDocumentation comment for this package) diff --git a/plugins/todo/src/api/TodoClient.ts b/plugins/todo/src/api/TodoClient.ts index f4fb4071e8..ab2bbea45b 100644 --- a/plugins/todo/src/api/TodoClient.ts +++ b/plugins/todo/src/api/TodoClient.ts @@ -19,16 +19,26 @@ import { ResponseError } from '@backstage/errors'; import { TodoApi, TodoListOptions, TodoListResult } from './types'; import { DiscoveryApi, IdentityApi } from '@backstage/core-plugin-api'; -interface Options { +/** + * Options for creating a todo client. + * + * @public + */ +export interface TodoClientOptions { discoveryApi: DiscoveryApi; identityApi: IdentityApi; } +/** + * An implementation of the TodoApi that talks to the todo plugin backend. + * + * @public + */ export class TodoClient implements TodoApi { private readonly discoveryApi: DiscoveryApi; private readonly identityApi: IdentityApi; - constructor(options: Options) { + constructor(options: TodoClientOptions) { this.discoveryApi = options.discoveryApi; this.identityApi = options.identityApi; } diff --git a/plugins/todo/src/api/index.ts b/plugins/todo/src/api/index.ts index d6771aeaba..b1d9792c95 100644 --- a/plugins/todo/src/api/index.ts +++ b/plugins/todo/src/api/index.ts @@ -15,5 +15,12 @@ */ export { TodoClient } from './TodoClient'; +export type { TodoClientOptions } from './TodoClient'; export { todoApiRef } from './types'; -export type { TodoApi } from './types'; +export type { + TodoApi, + TodoListOptions, + TodoListResult, + TodoItem, + TodoListFields, +} from './types'; diff --git a/plugins/todo/src/api/types.ts b/plugins/todo/src/api/types.ts index 018f1df536..f1f647f6e3 100644 --- a/plugins/todo/src/api/types.ts +++ b/plugins/todo/src/api/types.ts @@ -17,6 +17,11 @@ import { Entity } from '@backstage/catalog-model'; import { createApiRef } from '@backstage/core-plugin-api'; +/** + * TodoItem represents a single TODO comment in source code. + * + * @public + */ export type TodoItem = { /** The contents of the TODO comment */ text: string; @@ -37,23 +42,43 @@ export type TodoItem = { repoFilePath?: string; }; -type Fields = 'text' | 'tag' | 'author' | 'viewUrl' | 'repoFilePath'; +/** + * Fields that can be used to filter or order todo items. + * + * @public + */ +export type TodoListFields = + | 'text' + | 'tag' + | 'author' + | 'viewUrl' + | 'repoFilePath'; +/** + * Options used to list todo items. + * + * @public + */ export type TodoListOptions = { entity?: Entity; offset?: number; limit?: number; orderBy?: { - field: Fields; + field: TodoListFields; direction: 'asc' | 'desc'; }; filters?: { - field: Fields; + field: TodoListFields; /** Value to filter by, with '*' used as wildcard */ value: string; }[]; }; +/** + * The result of listing todos. + * + * @public + */ export type TodoListResult = { items: TodoItem[]; totalCount: number; @@ -61,10 +86,25 @@ export type TodoListResult = { limit: number; }; +/** + * The API used by the todo-plugin to list todos. + * + * @public + */ export interface TodoApi { + /** + * Lists todo items. + * + * @public + */ listTodos(options: TodoListOptions): Promise; } +/** + * ApiRef for the TodoApi. + * + * @public + */ export const todoApiRef = createApiRef({ id: 'plugin.todo.api', description: 'Lists TODOs', diff --git a/plugins/todo/src/index.ts b/plugins/todo/src/index.ts index d04df36f5e..92a85945ac 100644 --- a/plugins/todo/src/index.ts +++ b/plugins/todo/src/index.ts @@ -14,5 +14,13 @@ * limitations under the License. */ -export { todoApiRef } from './api'; +export { todoApiRef, TodoClient } from './api'; +export type { + TodoApi, + TodoListOptions, + TodoListResult, + TodoItem, + TodoListFields, + TodoClientOptions, +} from './api'; export { todoPlugin, EntityTodoContent } from './plugin'; diff --git a/plugins/todo/src/plugin.ts b/plugins/todo/src/plugin.ts index dd24304d0a..5415bbb902 100644 --- a/plugins/todo/src/plugin.ts +++ b/plugins/todo/src/plugin.ts @@ -22,8 +22,11 @@ import { identityApiRef, } from '@backstage/core-plugin-api'; -// import { rootRouteRef } from './routes'; - +/** + * The Todo plugin instance. + * + * @public + */ export const todoPlugin = createPlugin({ id: 'todo', apis: [ @@ -43,6 +46,11 @@ export const todoPlugin = createPlugin({ }, }); +/** + * An extension for displaying the list of todos on an entity page. + * + * @public + */ export const EntityTodoContent = todoPlugin.provide( createComponentExtension({ component: { From 9fbd23c7e54373209cbb1fc2b393247e750e4182 Mon Sep 17 00:00:00 2001 From: Patrik Oldsberg Date: Sat, 4 Sep 2021 17:42:35 +0200 Subject: [PATCH 2/3] plugins/todo: replace usage of deprecated serializeEntityRef Signed-off-by: Patrik Oldsberg --- plugins/todo/src/api/TodoClient.ts | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/plugins/todo/src/api/TodoClient.ts b/plugins/todo/src/api/TodoClient.ts index ab2bbea45b..f75e4b6954 100644 --- a/plugins/todo/src/api/TodoClient.ts +++ b/plugins/todo/src/api/TodoClient.ts @@ -14,7 +14,7 @@ * limitations under the License. */ -import { serializeEntityRef } from '@backstage/catalog-model'; +import { stringifyEntityRef } from '@backstage/catalog-model'; import { ResponseError } from '@backstage/errors'; import { TodoApi, TodoListOptions, TodoListResult } from './types'; import { DiscoveryApi, IdentityApi } from '@backstage/core-plugin-api'; @@ -55,7 +55,7 @@ export class TodoClient implements TodoApi { const query = new URLSearchParams(); if (entity) { - query.set('entity', serializeEntityRef(entity) as string); + query.set('entity', stringifyEntityRef(entity)); } if (typeof offset === 'number') { query.set('offset', String(offset)); From b07378742e866beedf4e1257fc4194957e939f0c Mon Sep 17 00:00:00 2001 From: Patrik Oldsberg Date: Sat, 4 Sep 2021 18:02:32 +0200 Subject: [PATCH 3/3] add changeset Signed-off-by: Patrik Oldsberg --- .changeset/forty-moons-boil.md | 5 +++++ 1 file changed, 5 insertions(+) create mode 100644 .changeset/forty-moons-boil.md diff --git a/.changeset/forty-moons-boil.md b/.changeset/forty-moons-boil.md new file mode 100644 index 0000000000..0000374546 --- /dev/null +++ b/.changeset/forty-moons-boil.md @@ -0,0 +1,5 @@ +--- +'@backstage/plugin-todo': patch +--- + +All types are now properly documented and exported.