add @config annotation to docs

Signed-off-by: Juan Pablo Garcia Ripa <juanpablog@spotify.com>

packages/repo-tools/src/commands/api-reports/api-extractor.ts

@@ -40,6 +40,8 @@ import {
   IDocNodeContainerParameters,
   TSDocTagSyntaxKind,
   TSDocConfiguration,
+  Standardization,
+  DocBlockTag,
   DocPlainText,
   DocLinkTag,
 } from '@microsoft/tsdoc';
@@ -342,7 +344,12 @@ export async function getTsDocConfig() {
     tagName: '@ignore',
     syntaxKind: TSDocTagSyntaxKind.ModifierTag,
   });
+  tsdocConfigFile.addTagDefinition({
+    tagName: '@config',
+    syntaxKind: TSDocTagSyntaxKind.BlockTag,
+  });
   tsdocConfigFile.setSupportForTag('@ignore', true);
+  tsdocConfigFile.setSupportForTag('@config', true);
   return tsdocConfigFile;
 }
 
@@ -879,9 +886,15 @@ export async function buildDocs({
           context.writer.writeLine();
           break;
         }
+        case 'BlockTag': {
+          const node = docNode as DocBlockTag;
+          if (node.tagName === '@config') {
+            context.writer.writeLine('## Related config ');
+          }
+          break;
+        }
         case DocCodeSpanLink.kind: {
           const node = docNode as DocLinkTag;
-
           if (node.codeDestination) {
             // TODO @sarabadu understand if we need `codeDestination` at all on this custom DocCodeSpanLink
             super.writeLinkTagWithCodeDestination(node, context);
@@ -938,8 +951,19 @@ export async function buildDocs({
         DocFrontMatter.kind,
         DocCodeSpanLink.kind,
       ]);
-      );
 
+      const def = {
+        tagName: '@config',
+        syntaxKind: TSDocTagSyntaxKind.BlockTag,
+        tagNameWithUpperCase: '@CONFIG',
+        standardization: Standardization.Extended,
+        allowMultiple: false,
+      };
+      (this._tsdocConfiguration as TSDocConfiguration).addTagDefinition(def);
+      (this._tsdocConfiguration as TSDocConfiguration).setSupportForTag(
+        def,
+        true,
+      );
       this._markdownEmitter = new CustomCustomMarkdownEmitter(newModel);
     }
 

plugins/proxy-backend/api-report.md

@@ -8,7 +8,7 @@ import express from 'express';
 import { Logger } from 'winston';
 import { PluginEndpointDiscovery } from '@backstage/backend-common';
 
-// @public (undocumented)
+// @public
 export function createRouter(options: RouterOptions): Promise<express.Router>;
 
 // @public (undocumented)

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

@@ -178,7 +178,24 @@ export function buildMiddleware(
   return createProxyMiddleware(filter, fullConfig);
 }
 
-/** @public */
+/**
+ * Creates a new {@link https://expressjs.com/en/api.html#router | "express router"} that proxy each target configured under the `proxy` key of the config
+ * @example
+ * ```ts
+ * let router = await createRouter({logger, config, discovery});
+ * ```
+ * @config
+ * ```yaml
+ * proxy:
+ *  simple-example: http://simple.example.com:8080 # Opt 1 Simple URL String
+ *  '/larger-example/v1': # Opt 2 `http-proxy-middleware` compatible object
+ *    target: http://larger.example.com:8080/svc.v1
+ *    headers:
+ *      Authorization: Bearer ${EXAMPLE_AUTH_TOKEN}
+ *```
+ * @see https://backstage.io/docs/plugins/proxying
+ * @public
+ */
 export async function createRouter(
   options: RouterOptions,
 ): Promise<express.Router> {