feat: add 'x-internal' extension property to OpenAPI spec

packages/rest/src/router/routing-table.ts

@@ -156,11 +156,13 @@ export class RoutingTable {
     const paths: PathObject = {};
 
     for (const route of this._router.list()) {
-      if (!paths[route.path]) {
-        paths[route.path] = {};
-      }
+      if (!route.spec['x-internal']) {
+        if (!paths[route.path]) {
+          paths[route.path] = {};
+        }
 
-      paths[route.path][route.verb] = route.spec;
+        paths[route.path][route.verb] = route.spec;
+      }
     }
 
     return paths;
@@ -187,6 +189,10 @@ export class RoutingTable {
   }
 }
 
+export interface LB4OperationObject extends OperationObject {
+  readonly 'x-internal'?: boolean;
+}
+
 /**
  * An entry in the routing table
  */
@@ -202,7 +208,7 @@ export interface RouteEntry {
   /**
    * OpenAPI operation spec
    */
-  readonly spec: OperationObject;
+  readonly spec: LB4OperationObject;
 
   /**
    * Update bindings for the request context

packages/rest/test/unit/rest.server/rest.server.open-api-spec.unit.ts

@@ -89,6 +89,29 @@ describe('RestServer.getApiSpec()', () => {
     });
   });
 
+  it('ignores routes marked as "x-internal" via app.route(route)', () => {
+    function greet() {}
+    function meet() {}
+    server.route(
+      new Route(
+        'get',
+        '/greet',
+        {'x-internal': true, responses: {}, spec: {}},
+        greet,
+      ),
+    );
+    server.route(new Route('get', '/meet', {responses: {}, spec: {}}, meet));
+    const spec = server.getApiSpec();
+    expect(spec.paths).to.eql({
+      '/meet': {
+        get: {
+          responses: {},
+          spec: {},
+        },
+      },
+    });
+  });
+
   it('returns routes registered via app.route(..., Controller, method)', () => {
     class MyController {
       greet() {}
@@ -116,6 +139,46 @@ describe('RestServer.getApiSpec()', () => {
     });
   });
 
+  it('ignores routes marked as "x-internal" via app.route(..., Controller, method)', () => {
+    class GreetController {
+      greet() {}
+    }
+
+    class MeetController {
+      meet() {}
+    }
+
+    server.route(
+      'get',
+      '/greet',
+      {'x-internal': true, responses: {}},
+      GreetController,
+      createControllerFactoryForClass(GreetController),
+      'greet',
+    );
+
+    server.route(
+      'get',
+      '/meet',
+      {responses: {}},
+      MeetController,
+      createControllerFactoryForClass(MeetController),
+      'meet',
+    );
+
+    const spec = server.getApiSpec();
+    expect(spec.paths).to.eql({
+      '/meet': {
+        get: {
+          responses: {},
+          'x-controller-name': 'MeetController',
+          'x-operation-name': 'meet',
+          tags: ['MeetController'],
+        },
+      },
+    });
+  });
+
   it('honors tags in the operation spec', () => {
     class MyController {
       @get('/greet', {responses: {'200': {description: ''}}, tags: ['MyTag']})