From 359f9d2d8cbe82e9c03230cc3915c35e2e248703 Mon Sep 17 00:00:00 2001 From: keshan Date: Mon, 21 Dec 2020 12:44:02 +0530 Subject: [PATCH 1/4] Introduced config schema for techdocs plugins --- .changeset/modern-timers-obey.md | 6 ++ plugins/techdocs-backend/config.d.ts | 46 ++++++++++++++ plugins/techdocs-backend/package.json | 6 +- plugins/techdocs/config.d.ts | 91 +++++++++++++++++++++++++++ plugins/techdocs/package.json | 83 +----------------------- 5 files changed, 150 insertions(+), 82 deletions(-) create mode 100644 .changeset/modern-timers-obey.md create mode 100644 plugins/techdocs-backend/config.d.ts create mode 100644 plugins/techdocs/config.d.ts diff --git a/.changeset/modern-timers-obey.md b/.changeset/modern-timers-obey.md new file mode 100644 index 0000000000..7268d4961d --- /dev/null +++ b/.changeset/modern-timers-obey.md @@ -0,0 +1,6 @@ +--- +'@backstage/plugin-techdocs': patch +'@backstage/plugin-techdocs-backend': patch +--- + +Added configuration schema for the commonly used properties of techdocs and techdocs-backend plugins diff --git a/plugins/techdocs-backend/config.d.ts b/plugins/techdocs-backend/config.d.ts new file mode 100644 index 0000000000..f3237c669a --- /dev/null +++ b/plugins/techdocs-backend/config.d.ts @@ -0,0 +1,46 @@ +/* + * Copyright 2020 Spotify AB + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +export interface Config { + /** Configuration options for the techdocs-backend plugin */ + techdocs: { + /** + * attr: 'storageUrl' - accepts a string value + * e.g. storageUrl: http://localhost:7000/api/techdocs/static/docs + */ + storageUrl: string; + /** + * documentation building process depends on the builder attr + * attr: 'builder' - accepts a string value + * e.g. builder: 'local' + * alternative: 'external' etc. + * @see http://backstage.io/docs/features/techdocs/configuration + */ + builder: string; + /** + * techdocs publisher information + */ + publisher: { + /** + * attr: 'type' - accepts a string value + * e.g. type: 'local' + * aleternatives: 'googleGcs' etc. + * @see http://backstage.io/docs/features/techdocs/configuration + */ + type: string; + }; + }; +} diff --git a/plugins/techdocs-backend/package.json b/plugins/techdocs-backend/package.json index 5552d87f3f..372c8aaa6e 100644 --- a/plugins/techdocs-backend/package.json +++ b/plugins/techdocs-backend/package.json @@ -48,6 +48,8 @@ "supertest": "^4.0.2" }, "files": [ - "dist" - ] + "dist", + "config.d.ts" + ], + "configSchema": "config.d.ts" } diff --git a/plugins/techdocs/config.d.ts b/plugins/techdocs/config.d.ts new file mode 100644 index 0000000000..a60fbed1b4 --- /dev/null +++ b/plugins/techdocs/config.d.ts @@ -0,0 +1,91 @@ +/* + * Copyright 2020 Spotify AB + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +export interface Config { + /** Configuration options for the techdocs plugin */ + techdocs: { + /** + * attr: 'requestUrl' - accepts a string value + * e.g. requestUrl: http://localhost:7000/api/techdocs + * @visibility frontend + */ + requestUrl: string; + /** + * attr: 'storageUrl' - accepts a string value + * e.g. storageUrl: http://localhost:7000/api/techdocs/static/docs + */ + storageUrl: string; + /** + * documentation building process depends on the builder attr + * attr: 'builder' - accepts a string value + * e.g. builder: 'local' + * alternative: 'external' etc. + * @see http://backstage.io/docs/features/techdocs/configuration + * @visibility frontend + */ + builder: string; + + /** + * techdocs publisher information + */ + generators?: { + /** + * attr: 'techdocs' - accepts a string value + * e.g. type: 'docker' + * aleternatives: 'local' etc. + * @see http://backstage.io/docs/features/techdocs/configuration + */ + techdocs: string; + }; + + /** + * techdocs publisher information + */ + publisher?: { + /** + * attr: 'type' - accepts a string value + * e.g. type: 'local' + * aleternatives: 'googleGcs' etc. + * @see http://backstage.io/docs/features/techdocs/configuration + */ + type: string; + + /** + * googleGcs required when 'type' is set to googleGcs, skip otherwise + */ + googleGcs?: { + /** + * API key used to write to a storage bucket. + * attr: 'credentials' - accepts a string value + * @visibility secret + */ + credentials: string; + /** + * GCP Project ID where the Cloud Storage Bucket is hosted. + * attr: 'projectId' - accepts a string value + * @visibility secret + */ + projectId: string; + /** + * Cloud Storage Bucket Name + * attr: 'bucketName' - accepts a string value + * @visibility secret + */ + bucketName: string; + }; + }; + }; +} diff --git a/plugins/techdocs/package.json b/plugins/techdocs/package.json index 361825e71a..2baebdcad0 100644 --- a/plugins/techdocs/package.json +++ b/plugins/techdocs/package.json @@ -63,85 +63,8 @@ "msw": "^0.21.2" }, "files": [ - "dist" + "dist", + "config.d.ts" ], - "configSchema": { - "$schema": "https://backstage.io/schema/config-v1", - "title": "@backstage/techdocs", - "type": "object", - "properties": { - "techdocs": { - "type": "object", - "properties": { - "requestUrl": { - "type": "string", - "visibility": "frontend" - }, - "storageUrl": { - "type": "string", - "visibility": "backend" - }, - "generators": { - "type": "object", - "properties": { - "techdocs": { - "type": "string", - "visibility": "backend" - } - } - }, - "builder": { - "type": "string", - "visibility": "frontend" - }, - "publisher": { - "oneOf": [ - { - "type": "object", - "properties": { - "type": { - "type": "string", - "const": "local", - "visibility": "backend" - } - } - }, - { - "type": "object", - "properties": { - "type": { - "type": "string", - "const": "googleGcs", - "visibility": "backend" - }, - "googleGcs": { - "type": "object", - "properties": { - "credentials": { - "type": "string", - "visibility": "secret" - }, - "projectId": { - "type": "string", - "visibility": "secret" - }, - "bucketName": { - "type": "string", - "visibility": "secret" - } - } - } - } - } - ] - } - }, - "required": [ - "requestUrl", - "storageUrl", - "builder" - ] - } - } - } + "configSchema": "config.d.ts" } From e53d4a2ca823efd3eccbd91e0c962e5ee7ec94cc Mon Sep 17 00:00:00 2001 From: keshan Date: Mon, 21 Dec 2020 16:25:49 +0530 Subject: [PATCH 2/4] updated based on the feedbacks provided --- plugins/techdocs-backend/config.d.ts | 9 ++-- plugins/techdocs/config.d.ts | 76 ++++++++++++++++------------ 2 files changed, 49 insertions(+), 36 deletions(-) diff --git a/plugins/techdocs-backend/config.d.ts b/plugins/techdocs-backend/config.d.ts index f3237c669a..bb76b21eae 100644 --- a/plugins/techdocs-backend/config.d.ts +++ b/plugins/techdocs-backend/config.d.ts @@ -13,7 +13,10 @@ * See the License for the specific language governing permissions and * limitations under the License. */ - +/** + * techdocs schema below is an abstract of what's used within techdocs-backend and for its visisbility + * to view the complete techdoc schema please refer: plugins/techdocs/config.d.ts + * */ export interface Config { /** Configuration options for the techdocs-backend plugin */ techdocs: { @@ -29,7 +32,7 @@ export interface Config { * alternative: 'external' etc. * @see http://backstage.io/docs/features/techdocs/configuration */ - builder: string; + builder: 'local' | 'external'; /** * techdocs publisher information */ @@ -40,7 +43,7 @@ export interface Config { * aleternatives: 'googleGcs' etc. * @see http://backstage.io/docs/features/techdocs/configuration */ - type: string; + type: 'local' | 'googleGcs' | 'awsS3'; }; }; } diff --git a/plugins/techdocs/config.d.ts b/plugins/techdocs/config.d.ts index a60fbed1b4..10adcb9fbd 100644 --- a/plugins/techdocs/config.d.ts +++ b/plugins/techdocs/config.d.ts @@ -36,7 +36,7 @@ export interface Config { * @see http://backstage.io/docs/features/techdocs/configuration * @visibility frontend */ - builder: string; + builder: 'local' | 'external'; /** * techdocs publisher information @@ -54,38 +54,48 @@ export interface Config { /** * techdocs publisher information */ - publisher?: { - /** - * attr: 'type' - accepts a string value - * e.g. type: 'local' - * aleternatives: 'googleGcs' etc. - * @see http://backstage.io/docs/features/techdocs/configuration - */ - type: string; + publisher?: + | { + /** + * attr: 'type' - accepts a string value + * e.g. type: 'local' + * aleternatives: 'googleGcs' etc. + * @see http://backstage.io/docs/features/techdocs/configuration + */ + type: 'local' | 'awsS3'; + } + | { + /** + * attr: 'type' - accepts a string value + * e.g. type: 'googleGcs' + * aleternatives: 'googleGcs' etc. + * @see http://backstage.io/docs/features/techdocs/configuration + */ + type: 'googleGcs'; - /** - * googleGcs required when 'type' is set to googleGcs, skip otherwise - */ - googleGcs?: { - /** - * API key used to write to a storage bucket. - * attr: 'credentials' - accepts a string value - * @visibility secret - */ - credentials: string; - /** - * GCP Project ID where the Cloud Storage Bucket is hosted. - * attr: 'projectId' - accepts a string value - * @visibility secret - */ - projectId: string; - /** - * Cloud Storage Bucket Name - * attr: 'bucketName' - accepts a string value - * @visibility secret - */ - bucketName: string; - }; - }; + /** + * googleGcs required when 'type' is set to googleGcs + */ + googleGcs?: { + /** + * API key used to write to a storage bucket. + * attr: 'credentials' - accepts a string value + * @visibility secret + */ + credentials: string; + /** + * GCP Project ID where the Cloud Storage Bucket is hosted. + * attr: 'projectId' - accepts a string value + * @visibility secret + */ + projectId: string; + /** + * Cloud Storage Bucket Name + * attr: 'bucketName' - accepts a string value + * @visibility secret + */ + bucketName: string; + }; + }; }; } From 851dde45f7c95520822423df8fa425e67f07f2cb Mon Sep 17 00:00:00 2001 From: keshan Date: Mon, 21 Dec 2020 16:31:01 +0530 Subject: [PATCH 3/4] updated the missed attr change --- plugins/techdocs/config.d.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/plugins/techdocs/config.d.ts b/plugins/techdocs/config.d.ts index 10adcb9fbd..543579e85f 100644 --- a/plugins/techdocs/config.d.ts +++ b/plugins/techdocs/config.d.ts @@ -48,7 +48,7 @@ export interface Config { * aleternatives: 'local' etc. * @see http://backstage.io/docs/features/techdocs/configuration */ - techdocs: string; + techdocs: 'local' | 'docker'; }; /** From 23cee0d8313d03576c14f5af59faeed8b292ef27 Mon Sep 17 00:00:00 2001 From: keshan Date: Mon, 21 Dec 2020 16:33:39 +0530 Subject: [PATCH 4/4] typo corrected --- plugins/techdocs-backend/config.d.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/plugins/techdocs-backend/config.d.ts b/plugins/techdocs-backend/config.d.ts index bb76b21eae..b51d86138a 100644 --- a/plugins/techdocs-backend/config.d.ts +++ b/plugins/techdocs-backend/config.d.ts @@ -14,7 +14,7 @@ * limitations under the License. */ /** - * techdocs schema below is an abstract of what's used within techdocs-backend and for its visisbility + * techdocs schema below is an abstract of what's used within techdocs-backend and for its visibility * to view the complete techdoc schema please refer: plugins/techdocs/config.d.ts * */ export interface Config {