diff --git a/plugins/techdocs/api-report.md b/plugins/techdocs/api-report.md index fc7b515167..7aed7139db 100644 --- a/plugins/techdocs/api-report.md +++ b/plugins/techdocs/api-report.md @@ -13,6 +13,7 @@ import { CSSProperties } from '@material-ui/styles'; import { DiscoveryApi } from '@backstage/core-plugin-api'; import { Entity } from '@backstage/catalog-model'; import { EntityName } from '@backstage/catalog-model'; +import { FetchApi } from '@backstage/core-plugin-api'; import { IdentityApi } from '@backstage/core-plugin-api'; import { LocationSpec } from '@backstage/catalog-model'; import { default as React_2 } from 'react'; @@ -197,16 +198,11 @@ export const Reader: ({ // @public (undocumented) export const Router: () => JSX.Element; -// Warning: (ae-missing-release-tag) "SyncResult" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// -// @public (undocumented) +// @public export type SyncResult = 'cached' | 'updated'; -// Warning: (ae-missing-release-tag) "TechDocsApi" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// -// @public (undocumented) +// @public export interface TechDocsApi { - // (undocumented) getApiOrigin(): Promise; // Warning: (ae-forgotten-export) The symbol "TechDocsEntityMetadata" needs to be exported by the entry point index.d.ts // @@ -218,23 +214,16 @@ export interface TechDocsApi { getTechDocsMetadata(entityId: EntityName): Promise; } -// Warning: (ae-missing-release-tag) "techdocsApiRef" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// -// @public (undocumented) +// @public export const techdocsApiRef: ApiRef; -// Warning: (ae-missing-release-tag) "TechDocsClient" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public export class TechDocsClient implements TechDocsApi { - constructor({ - configApi, - discoveryApi, - identityApi, - }: { + constructor(options: { configApi: Config; discoveryApi: DiscoveryApi; identityApi: IdentityApi; + fetchApi?: FetchApi; }); // (undocumented) configApi: Config; @@ -347,11 +336,8 @@ export const TechDocsReaderPage: ({ children, }: TechDocsPageProps) => JSX.Element; -// Warning: (ae-missing-release-tag) "TechDocsStorageApi" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// -// @public (undocumented) +// @public export interface TechDocsStorageApi { - // (undocumented) getApiOrigin(): Promise; // (undocumented) getBaseUrl( @@ -372,23 +358,31 @@ export interface TechDocsStorageApi { ): Promise; } -// Warning: (ae-missing-release-tag) "techdocsStorageApiRef" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// -// @public (undocumented) +// @public export const techdocsStorageApiRef: ApiRef; -// Warning: (ae-missing-release-tag) "TechDocsStorageClient" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) +// Warning: (tsdoc-malformed-html-name) Invalid HTML element: Expecting an HTML name +// Warning: (tsdoc-malformed-html-name) Invalid HTML element: Expecting an HTML name +// Warning: (tsdoc-malformed-html-name) Invalid HTML element: Expecting an HTML name +// Warning: (tsdoc-malformed-html-name) Invalid HTML element: Expecting an HTML name +// Warning: (tsdoc-malformed-html-name) Invalid HTML element: Expecting an HTML name +// Warning: (tsdoc-malformed-html-name) Invalid HTML element: Expecting an HTML name +// Warning: (tsdoc-malformed-html-name) Invalid HTML element: A space is not allowed here +// Warning: (tsdoc-escape-greater-than) The ">" character should be escaped using a backslash to avoid confusion with an HTML tag +// Warning: (tsdoc-escape-greater-than) The ">" character should be escaped using a backslash to avoid confusion with an HTML tag +// Warning: (tsdoc-escape-greater-than) The ">" character should be escaped using a backslash to avoid confusion with an HTML tag +// Warning: (tsdoc-escape-greater-than) The ">" character should be escaped using a backslash to avoid confusion with an HTML tag +// Warning: (tsdoc-escape-greater-than) The ">" character should be escaped using a backslash to avoid confusion with an HTML tag +// Warning: (tsdoc-escape-greater-than) The ">" character should be escaped using a backslash to avoid confusion with an HTML tag +// Warning: (tsdoc-escape-greater-than) The ">" character should be escaped using a backslash to avoid confusion with an HTML tag // // @public export class TechDocsStorageClient implements TechDocsStorageApi { - constructor({ - configApi, - discoveryApi, - identityApi, - }: { + constructor(options: { configApi: Config; discoveryApi: DiscoveryApi; identityApi: IdentityApi; + fetchApi?: FetchApi; }); // (undocumented) configApi: Config; diff --git a/plugins/techdocs/src/api.ts b/plugins/techdocs/src/api.ts index cd130f083d..4566bbf028 100644 --- a/plugins/techdocs/src/api.ts +++ b/plugins/techdocs/src/api.ts @@ -18,17 +18,40 @@ import { EntityName } from '@backstage/catalog-model'; import { TechDocsEntityMetadata, TechDocsMetadata } from './types'; import { createApiRef } from '@backstage/core-plugin-api'; +/** + * Utility API reference for the {@link TechDocsStorageApi}. + * + * @public + */ export const techdocsStorageApiRef = createApiRef({ id: 'plugin.techdocs.storageservice', }); +/** + * Utility API reference for the {@link TechDocsApi}. + * + * @public + */ export const techdocsApiRef = createApiRef({ id: 'plugin.techdocs.service', }); +/** + * The outcome of a docs sync operation. + * + * @public + */ export type SyncResult = 'cached' | 'updated'; +/** + * API which talks to TechDocs storage to fetch files to render. + * + * @public + */ export interface TechDocsStorageApi { + /** + * Set to techdocs.requestUrl as the URL for techdocs-backend API. + */ getApiOrigin(): Promise; getStorageUrl(): Promise; getBuilder(): Promise; @@ -44,7 +67,15 @@ export interface TechDocsStorageApi { ): Promise; } +/** + * API to talk to techdocs-backend. + * + * @public + */ export interface TechDocsApi { + /** + * Set to techdocs.requestUrl as the URL for techdocs-backend API. + */ getApiOrigin(): Promise; getTechDocsMetadata(entityId: EntityName): Promise; getEntityMetadata(entityId: EntityName): Promise; diff --git a/plugins/techdocs/src/client.ts b/plugins/techdocs/src/client.ts index 5cf33ac8d5..6f381a5bd9 100644 --- a/plugins/techdocs/src/client.ts +++ b/plugins/techdocs/src/client.ts @@ -16,7 +16,11 @@ import { EntityName } from '@backstage/catalog-model'; import { Config } from '@backstage/config'; -import { DiscoveryApi, IdentityApi } from '@backstage/core-plugin-api'; +import { + DiscoveryApi, + FetchApi, + IdentityApi, +} from '@backstage/core-plugin-api'; import { NotFoundError, ResponseError } from '@backstage/errors'; import { EventSourcePolyfill } from 'event-source-polyfill'; import { SyncResult, TechDocsApi, TechDocsStorageApi } from './api'; @@ -24,24 +28,25 @@ import { TechDocsEntityMetadata, TechDocsMetadata } from './types'; /** * API to talk to `techdocs-backend`. + * + * @public */ export class TechDocsClient implements TechDocsApi { public configApi: Config; public discoveryApi: DiscoveryApi; public identityApi: IdentityApi; + private fetchApi: FetchApi; - constructor({ - configApi, - discoveryApi, - identityApi, - }: { + constructor(options: { configApi: Config; discoveryApi: DiscoveryApi; identityApi: IdentityApi; + fetchApi?: FetchApi; }) { - this.configApi = configApi; - this.discoveryApi = discoveryApi; - this.identityApi = identityApi; + this.configApi = options.configApi; + this.discoveryApi = options.discoveryApi; + this.identityApi = options.identityApi; + this.fetchApi = options.fetchApi ?? { fetch }; } async getApiOrigin(): Promise { @@ -67,7 +72,7 @@ export class TechDocsClient implements TechDocsApi { const requestUrl = `${apiOrigin}/metadata/techdocs/${namespace}/${kind}/${name}`; const { token } = await this.identityApi.getCredentials(); - const request = await fetch(`${requestUrl}`, { + const request = await this.fetchApi.fetch(`${requestUrl}`, { headers: token ? { Authorization: `Bearer ${token}` } : {}, }); @@ -95,7 +100,7 @@ export class TechDocsClient implements TechDocsApi { const requestUrl = `${apiOrigin}/metadata/entity/${namespace}/${kind}/${name}`; const { token } = await this.identityApi.getCredentials(); - const request = await fetch(`${requestUrl}`, { + const request = await this.fetchApi.fetch(`${requestUrl}`, { headers: token ? { Authorization: `Bearer ${token}` } : {}, }); @@ -109,24 +114,28 @@ export class TechDocsClient implements TechDocsApi { /** * API which talks to TechDocs storage to fetch files to render. +<<<<<<< HEAD +======= + * + * @public +>>>>>>> 31c54b8ea2 (Make the techdocs APIs use the FetchApi) */ export class TechDocsStorageClient implements TechDocsStorageApi { public configApi: Config; public discoveryApi: DiscoveryApi; public identityApi: IdentityApi; + private fetchApi: FetchApi; - constructor({ - configApi, - discoveryApi, - identityApi, - }: { + constructor(options: { configApi: Config; discoveryApi: DiscoveryApi; identityApi: IdentityApi; + fetchApi?: FetchApi; }) { - this.configApi = configApi; - this.discoveryApi = discoveryApi; - this.identityApi = identityApi; + this.configApi = options.configApi; + this.discoveryApi = options.discoveryApi; + this.identityApi = options.identityApi; + this.fetchApi = options.fetchApi ?? { fetch }; } async getApiOrigin(): Promise { @@ -162,7 +171,7 @@ export class TechDocsStorageClient implements TechDocsStorageApi { const url = `${storageUrl}/${namespace}/${kind}/${name}/${path}`; const { token } = await this.identityApi.getCredentials(); - const request = await fetch( + const request = await this.fetchApi.fetch( `${url.endsWith('/') ? url : `${url}/`}index.html`, { headers: token ? { Authorization: `Bearer ${token}` } : {}, diff --git a/plugins/techdocs/src/plugin.ts b/plugins/techdocs/src/plugin.ts index 844003987a..274d1904d8 100644 --- a/plugins/techdocs/src/plugin.ts +++ b/plugins/techdocs/src/plugin.ts @@ -28,6 +28,7 @@ import { createPlugin, createRoutableExtension, discoveryApiRef, + fetchApiRef, identityApiRef, } from '@backstage/core-plugin-api'; @@ -40,12 +41,14 @@ export const techdocsPlugin = createPlugin({ configApi: configApiRef, discoveryApi: discoveryApiRef, identityApi: identityApiRef, + fetchApi: fetchApiRef, }, - factory: ({ configApi, discoveryApi, identityApi }) => + factory: ({ configApi, discoveryApi, identityApi, fetchApi }) => new TechDocsStorageClient({ configApi, discoveryApi, identityApi, + fetchApi, }), }), createApiFactory({ @@ -54,12 +57,14 @@ export const techdocsPlugin = createPlugin({ configApi: configApiRef, discoveryApi: discoveryApiRef, identityApi: identityApiRef, + fetchApi: fetchApiRef, }, - factory: ({ configApi, discoveryApi, identityApi }) => + factory: ({ configApi, discoveryApi, identityApi, fetchApi }) => new TechDocsClient({ configApi, discoveryApi, identityApi, + fetchApi, }), }), ], diff --git a/plugins/techdocs/src/setupTests.ts b/plugins/techdocs/src/setupTests.ts index 963c0f188b..c1d649f2ad 100644 --- a/plugins/techdocs/src/setupTests.ts +++ b/plugins/techdocs/src/setupTests.ts @@ -15,3 +15,4 @@ */ import '@testing-library/jest-dom'; +import 'cross-fetch/polyfill';