Merge pull request #3336 from backstage/mob/techdocs-storage-solutions-spec

plugins/techdocs/src/api.ts

@@ -41,6 +41,11 @@ export interface TechDocs {
   getMetadata(metadataType: string, entityId: ParsedEntityId): Promise<string>;
 }
 
+/**
+ * API to talk to techdocs-backend.
+ *
+ * @property {string} apiOrigin Set to techdocs.requestUrl as the URL for techdocs-backend API
+ */
 export class TechDocsApi implements TechDocs {
   public apiOrigin: string;
 
@@ -60,6 +65,11 @@ export class TechDocsApi implements TechDocs {
   }
 }
 
+/**
+ * API which talks to TechDocs storage to fetch files to render.
+ *
+ * @property {string} apiOrigin Set to techdocs.requestUrl as the URL for techdocs-backend API
+ */
 export class TechDocsStorageApi implements TechDocsStorage {
   public apiOrigin: string;
 
@@ -67,6 +77,14 @@ export class TechDocsStorageApi implements TechDocsStorage {
     this.apiOrigin = apiOrigin;
   }
 
+  /**
+   * Fetch HTML content as text for an individual docs page in an entity's docs site.
+   *
+   * @param {ParsedEntityId} entityId Object containing entity data like name, namespace, etc.
+   * @param {string} path The unique path to an individual docs page e.g. overview/what-is-new
+   * @returns {string} HTML content of the docs page as string
+   * @throws {Error} Throws error when the page is not found.
+   */
   async getEntityDocs(entityId: ParsedEntityId, path: string) {
     const { kind, namespace, name } = entityId;
 

plugins/techdocs/src/plugin.ts

@@ -57,6 +57,7 @@ export const rootCatalogDocsRouteRef = createRouteRef({
   title: 'Docs',
 });
 
+// TODO: Use discovery API for frontend to get URL for techdocs-backend instead of requestUrl
 export const plugin = createPlugin({
   id: 'techdocs',
   apis: [

plugins/techdocs/src/types.ts

@@ -14,6 +14,12 @@
  * limitations under the License.
  */
 
+/**
+ * To uniquely identify an entity in Backstage.
+ * @property {string} kind
+ * @property {string} namespace
+ * @property {string} name
+ */
 export type ParsedEntityId = {
   kind: string;
   namespace?: string;