From 5bcd49ae9dbac893c6c09425fdbd627793f95096 Mon Sep 17 00:00:00 2001 From: Emma Indal Date: Fri, 24 Sep 2021 10:54:00 +0200 Subject: [PATCH 1/6] Add a how to guide on how to implement your custom techdocs apis Signed-off-by: Emma Indal --- docs/features/techdocs/how-to-guides.md | 53 +++++++++++++++++++++++++ 1 file changed, 53 insertions(+) diff --git a/docs/features/techdocs/how-to-guides.md b/docs/features/techdocs/how-to-guides.md index 326ac02969..75feb86d7f 100644 --- a/docs/features/techdocs/how-to-guides.md +++ b/docs/features/techdocs/how-to-guides.md @@ -217,3 +217,56 @@ techdocs: [beta-migrate-bug]: https://github.com/backstage/backstage/issues/new?assignees=&labels=bug&template=bug_template.md&title=[TechDocs]%20Unable%20to%20run%20beta%20migration [using-cloud-storage]: ./using-cloud-storage.md + +## How to implement your own TechDocs APIs + +The TechDocs plugin provides implementations of two primary apis by default, the +[TechDocsStorageApi](https://github.com/backstage/backstage/blob/55114cfeb7045e3e5eeeaf67546b58964f4adcc7/plugins/techdocs/src/api.ts#L33), +which is responsible for talking to TechDocs storage to fetch files to render, +and +[TechDocsApi](https://github.com/backstage/backstage/blob/55114cfeb7045e3e5eeeaf67546b58964f4adcc7/plugins/techdocs/src/api.ts#L49), +which is responsible for talking to techdocs-backend. + +There may be occasions where you need to implement these two apis yourself, to +customize it to your own needs. The purpose of this guide is to walk you through +how to do that in two steps. + +1. Implement the `TechDocsStorageApi` and `TechDocsApi` interfaces according to + your needs. + +```typescript +export class TechDocsCustomStorageApi implements TechDocsStorageApi { + // your implementation +} + +export class TechDocsCustomApiClient implements TechDocsApi { + // your implementation +} +``` + +2. Override the api refs `techdocsStorageApiRef` and `techdocsApiRef` with your + new implemented APIs in the `App.tsx` using `ApiFactories`. + [Read more about App APIs](https://backstage.io/docs/api/utility-apis#app-apis). + +```typescript +const app = createApp({ + apis: [ + // TechDocsStorageApi + createApiFactory({ + api: techdocsStorageApiRef, + deps: { discoveryApi: discoveryApiRef, configApi: configApiRef }, + factory({ discoveryApi, configApi }) { + return new TechDocsCustomStorageApi({ discoveryApi, configApi }); + }, + }), + // TechDocsApi + createApiFactory({ + api: techdocsApiRef, + deps: { discoveryApi: discoveryApiRef }, + factory({ discoveryApi }) { + return new TechDocsCustomApiClient({ discoveryApi }); + }, + }), + ], +}); +``` From d1e0287c83918e95e82d37f376d1562d866f85f5 Mon Sep 17 00:00:00 2001 From: bodilb Date: Fri, 24 Sep 2021 13:43:24 +0200 Subject: [PATCH 2/6] Update docs/features/techdocs/how-to-guides.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Bodil Björklund  Signed-off-by: Emma Indal --- docs/features/techdocs/how-to-guides.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/features/techdocs/how-to-guides.md b/docs/features/techdocs/how-to-guides.md index 75feb86d7f..bfd95be4d5 100644 --- a/docs/features/techdocs/how-to-guides.md +++ b/docs/features/techdocs/how-to-guides.md @@ -220,7 +220,7 @@ https://github.com/backstage/backstage/issues/new?assignees=&labels=bug&template ## How to implement your own TechDocs APIs -The TechDocs plugin provides implementations of two primary apis by default, the +The TechDocs plugin provides implementations of two primary apis by default: the [TechDocsStorageApi](https://github.com/backstage/backstage/blob/55114cfeb7045e3e5eeeaf67546b58964f4adcc7/plugins/techdocs/src/api.ts#L33), which is responsible for talking to TechDocs storage to fetch files to render, and From 6a63cde923cd885bb6c42d9d7c38de5a3847ac42 Mon Sep 17 00:00:00 2001 From: bodilb Date: Fri, 24 Sep 2021 13:43:57 +0200 Subject: [PATCH 3/6] Update docs/features/techdocs/how-to-guides.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Bodil Björklund  Signed-off-by: Emma Indal --- docs/features/techdocs/how-to-guides.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/features/techdocs/how-to-guides.md b/docs/features/techdocs/how-to-guides.md index bfd95be4d5..a79e93fd4a 100644 --- a/docs/features/techdocs/how-to-guides.md +++ b/docs/features/techdocs/how-to-guides.md @@ -227,8 +227,8 @@ and [TechDocsApi](https://github.com/backstage/backstage/blob/55114cfeb7045e3e5eeeaf67546b58964f4adcc7/plugins/techdocs/src/api.ts#L49), which is responsible for talking to techdocs-backend. -There may be occasions where you need to implement these two apis yourself, to -customize it to your own needs. The purpose of this guide is to walk you through +There may be occasions where you need to implement these two APIs yourself, to +customize them to your own needs. The purpose of this guide is to walk you through how to do that in two steps. 1. Implement the `TechDocsStorageApi` and `TechDocsApi` interfaces according to From 24ecb5414ae3d7968bde5d3f01ad46869d986233 Mon Sep 17 00:00:00 2001 From: bodilb Date: Fri, 24 Sep 2021 13:44:05 +0200 Subject: [PATCH 4/6] Update docs/features/techdocs/how-to-guides.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Bodil Björklund  Signed-off-by: Emma Indal --- docs/features/techdocs/how-to-guides.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/features/techdocs/how-to-guides.md b/docs/features/techdocs/how-to-guides.md index a79e93fd4a..b4cee15cd1 100644 --- a/docs/features/techdocs/how-to-guides.md +++ b/docs/features/techdocs/how-to-guides.md @@ -244,7 +244,7 @@ export class TechDocsCustomApiClient implements TechDocsApi { } ``` -2. Override the api refs `techdocsStorageApiRef` and `techdocsApiRef` with your +2. Override the API refs `techdocsStorageApiRef` and `techdocsApiRef` with your new implemented APIs in the `App.tsx` using `ApiFactories`. [Read more about App APIs](https://backstage.io/docs/api/utility-apis#app-apis). From 659c395eae5f7306119a99c95723432ffe188dd9 Mon Sep 17 00:00:00 2001 From: bodilb Date: Fri, 24 Sep 2021 13:44:37 +0200 Subject: [PATCH 5/6] Update docs/features/techdocs/how-to-guides.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Bodil Björklund  Signed-off-by: Emma Indal --- docs/features/techdocs/how-to-guides.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/features/techdocs/how-to-guides.md b/docs/features/techdocs/how-to-guides.md index b4cee15cd1..244126e680 100644 --- a/docs/features/techdocs/how-to-guides.md +++ b/docs/features/techdocs/how-to-guides.md @@ -220,7 +220,7 @@ https://github.com/backstage/backstage/issues/new?assignees=&labels=bug&template ## How to implement your own TechDocs APIs -The TechDocs plugin provides implementations of two primary apis by default: the +The TechDocs plugin provides implementations of two primary APIs by default: the [TechDocsStorageApi](https://github.com/backstage/backstage/blob/55114cfeb7045e3e5eeeaf67546b58964f4adcc7/plugins/techdocs/src/api.ts#L33), which is responsible for talking to TechDocs storage to fetch files to render, and From 51fb9eb42a30f2e25d4e7d81aa84aea7fe5db782 Mon Sep 17 00:00:00 2001 From: Emma Indal Date: Fri, 24 Sep 2021 13:55:37 +0200 Subject: [PATCH 6/6] fix formatting Signed-off-by: Emma Indal --- docs/features/techdocs/how-to-guides.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/features/techdocs/how-to-guides.md b/docs/features/techdocs/how-to-guides.md index 244126e680..db093caa39 100644 --- a/docs/features/techdocs/how-to-guides.md +++ b/docs/features/techdocs/how-to-guides.md @@ -228,8 +228,8 @@ and which is responsible for talking to techdocs-backend. There may be occasions where you need to implement these two APIs yourself, to -customize them to your own needs. The purpose of this guide is to walk you through -how to do that in two steps. +customize them to your own needs. The purpose of this guide is to walk you +through how to do that in two steps. 1. Implement the `TechDocsStorageApi` and `TechDocsApi` interfaces according to your needs.