techdocs: Add JSON Schema config

Show better error if techdocs.builder is set to 'ci' and if no docs are found.
Return 404 from googleStorage client when a file is not found.

app-config.yaml

@@ -65,7 +65,7 @@ organization:
 techdocs:
   requestUrl: http://localhost:7000/api/techdocs
   storageUrl: http://localhost:7000/api/techdocs/static/docs
-  docsBuilder: 'local' # Alternatives - 'ci'
+  builder: 'local' # Alternatives - 'ci'
   generators:
     techdocs: 'docker' # Alternatives - 'local'
   publisher:

packages/techdocs-common/src/stages/publish/googleStorage.ts

@@ -180,8 +180,8 @@ export class GoogleGCSPublish implements PublisherBase {
         .file(filePath)
         .createReadStream()
         .on('error', err => {
-          this.logger.error(err.message);
-          res.send(err.message);
+          this.logger.warn(err.message);
+          res.status(404).send(err.message);
         })
         .on('data', chunk => {
           fileStreamChunks.push(chunk);

plugins/techdocs-backend/src/service/router.ts

@@ -120,10 +120,10 @@ export async function createRouter({
       );
     }
 
-    // techdocs-backend will only try to build documentation for an entity if techdocs.docsBuilder is set to 'local'
+    // techdocs-backend will only try to build documentation for an entity if techdocs.builder is set to 'local'
     // If set to 'ci', it will only try to fetch and assume that that CI/CD pipeline of the repository hosting the
     // entity's documentation is responsible for building and publishing documentation to the storage provider.
-    if (config.getString('techdocs.docsBuilder') === 'local') {
+    if (config.getString('techdocs.builder') === 'local') {
       const docsBuilder = new DocsBuilder({
         preparers,
         generators,

plugins/techdocs/package.json

@@ -68,11 +68,56 @@
             "visibility": "frontend"
           },
           "storageUrl": {
-            "type": "string"
+            "type": "string",
+            "visibility": "backend"
+          },
+          "generators": {
+            "type": "object",
+            "properties": {
+              "techdocs": {
+                "type": "string",
+                "visibility": "backend"
+              }
+            }
+          },
+          "builder": {
+            "type": "string",
+            "visibility": "frontend"
+          },
+          "publisher": {
+            "type": "object",
+            "properties": {
+              "type": {
+                "type": "string",
+                "visibility": "backend"
+              },
+              "google": {
+                "type": "object",
+                "properties": {
+                  "pathToKey": {
+                    "type": "string",
+                    "visibility": "secret"
+                  },
+                  "projectId": {
+                    "type": "string",
+                    "visibility": "secret"
+                  },
+                  "bucketName": {
+                    "type": "string",
+                    "visibility": "secret"
+                  }
+                }
+              }
+            },
+            "required": [
+              "type"
+            ]
           }
         },
         "required": [
-          "requestUrl"
+          "requestUrl",
+          "storageUrl",
+          "builder"
         ]
       }
     }

plugins/techdocs/src/reader/components/TechDocsNotFound.tsx

@@ -15,18 +15,30 @@
  */
 
 import React from 'react';
-import { ErrorPage } from '@backstage/core';
+import { ErrorPage, useApi, configApiRef } from '@backstage/core';
 
 type Props = {
   errorMessage?: string;
 };
 
 export const TechDocsNotFound = ({ errorMessage }: Props) => {
+  const techdocsBuilder = useApi(configApiRef).getOptionalString(
+    'techdocs.builder',
+  );
+
+  let additionalInfo = '';
+  if (techdocsBuilder === 'ci') {
+    additionalInfo =
+      "Note that you have set techdocs.builder to 'ci' in your config, which means this Backstage app will not " +
+      "build docs if they are not found. Make sure the project's CI/CD pipeline builds and publishes docs. Or " +
+      "change techdocs.builder to 'local' to build docs from this Backstage instance.";
+  }
+
   return (
     <ErrorPage
       status="404"
       statusMessage={errorMessage || 'Documentation not found'}
-      additionalInfo={window.location.pathname}
+      additionalInfo={additionalInfo}
     />
   );
 };