diff --git a/packages/backend-plugin-api/src/services/definitions/cacheServiceRef.ts b/packages/backend-plugin-api/src/services/definitions/cacheServiceRef.ts
index 439a2b645d..0b572f1712 100644
--- a/packages/backend-plugin-api/src/services/definitions/cacheServiceRef.ts
+++ b/packages/backend-plugin-api/src/services/definitions/cacheServiceRef.ts
@@ -17,6 +17,9 @@
 import { createServiceRef } from '../system/types';
 import { PluginCacheManager } from '@backstage/backend-common';
 
+/**
+ * @public
+ */
 export const cacheServiceRef = createServiceRef<PluginCacheManager>({
   id: 'core.cache',
 });
diff --git a/packages/backend-plugin-api/src/services/definitions/configServiceRef.ts b/packages/backend-plugin-api/src/services/definitions/configServiceRef.ts
index 9a4199967d..ba5dcacdc8 100644
--- a/packages/backend-plugin-api/src/services/definitions/configServiceRef.ts
+++ b/packages/backend-plugin-api/src/services/definitions/configServiceRef.ts
@@ -17,6 +17,9 @@
 import { Config } from '@backstage/config';
 import { createServiceRef } from '../system/types';
 
+/**
+ * @public
+ */
 export const configServiceRef = createServiceRef<Config>({
   id: 'core.config',
 });
diff --git a/packages/backend-plugin-api/src/services/definitions/databaseServiceRef.ts b/packages/backend-plugin-api/src/services/definitions/databaseServiceRef.ts
index 62f7f8a157..b41159dc9e 100644
--- a/packages/backend-plugin-api/src/services/definitions/databaseServiceRef.ts
+++ b/packages/backend-plugin-api/src/services/definitions/databaseServiceRef.ts
@@ -17,6 +17,9 @@
 import { PluginDatabaseManager } from '@backstage/backend-common';
 import { createServiceRef } from '../system/types';
 
+/**
+ * @public
+ */
 export const databaseServiceRef = createServiceRef<PluginDatabaseManager>({
   id: 'core.database',
 });
diff --git a/packages/backend-plugin-api/src/services/definitions/discoveryServiceRef.ts b/packages/backend-plugin-api/src/services/definitions/discoveryServiceRef.ts
index 3dfd5fa62b..675ac206a2 100644
--- a/packages/backend-plugin-api/src/services/definitions/discoveryServiceRef.ts
+++ b/packages/backend-plugin-api/src/services/definitions/discoveryServiceRef.ts
@@ -17,6 +17,9 @@
 import { createServiceRef } from '../system/types';
 import { PluginEndpointDiscovery } from '@backstage/backend-common';
 
+/**
+ * @public
+ */
 export const discoveryServiceRef = createServiceRef<PluginEndpointDiscovery>({
   id: 'core.discovery',
 });
diff --git a/packages/backend-plugin-api/src/services/definitions/httpRouterServiceRef.ts b/packages/backend-plugin-api/src/services/definitions/httpRouterServiceRef.ts
index 65a01fde3a..fbc5a27e87 100644
--- a/packages/backend-plugin-api/src/services/definitions/httpRouterServiceRef.ts
+++ b/packages/backend-plugin-api/src/services/definitions/httpRouterServiceRef.ts
@@ -17,28 +17,16 @@
 import { createServiceRef } from '../system/types';
 import { Handler } from 'express';
 
-//   const apiRouter = Router();
-//  apiRouter.use('/catalog', await catalog(catalogEnv));
-// const service = createServiceBuilder(module)
-// .loadConfig(config)
-// .addRouter('', await healthcheck(healthcheckEnv))
-// .addRouter('', metricsHandler())
-// .addRouter('/api', apiRouter)
-// .addRouter('', await app(appEnv));
-
-// interface BackstageRequest extends Request {
-//   identity?: BackstageIdentity;
-//   context?: Context;
-// }
-
-// interface RequestIdentityService {
-//   getRequestIdentity(req: Request): BackstageIdentity | undefined;
-// }
-
+/**
+ * @public
+ */
 export interface HttpRouterService {
   use(handler: Handler): void;
 }
 
+/**
+ * @public
+ */
 export const httpRouterServiceRef = createServiceRef<HttpRouterService>({
   id: 'core.httpRouter',
 });
diff --git a/packages/backend-plugin-api/src/services/definitions/index.ts b/packages/backend-plugin-api/src/services/definitions/index.ts
index 556aa88c72..797cfb5a76 100644
--- a/packages/backend-plugin-api/src/services/definitions/index.ts
+++ b/packages/backend-plugin-api/src/services/definitions/index.ts
@@ -14,18 +14,6 @@
  * limitations under the License.
  */
 
-// export type PluginEnvironment = {
-//   logger: Logger;
-//   cache: PluginCacheManager;
-//   database: PluginDatabaseManager;
-//   config: Config;
-//   reader: UrlReader;
-//   discovery: PluginEndpointDiscovery;
-//   tokenManager: TokenManager;
-//   permissions: PermissionEvaluator | PermissionAuthorizer;
-//   scheduler: PluginTaskScheduler;
-// };
-
 export { configServiceRef } from './configServiceRef';
 export { httpRouterServiceRef } from './httpRouterServiceRef';
 export type { HttpRouterService } from './httpRouterServiceRef';
diff --git a/packages/backend-plugin-api/src/services/definitions/loggerServiceRef.ts b/packages/backend-plugin-api/src/services/definitions/loggerServiceRef.ts
index 564ce15ded..e99bc4e7d4 100644
--- a/packages/backend-plugin-api/src/services/definitions/loggerServiceRef.ts
+++ b/packages/backend-plugin-api/src/services/definitions/loggerServiceRef.ts
@@ -16,11 +16,17 @@
 
 import { createServiceRef } from '../system/types';
 
+/**
+ * @public
+ */
 export interface Logger {
   info(message: string): void;
   child(fields: { [name: string]: string }): Logger;
 }
 
+/**
+ * @public
+ */
 export const loggerServiceRef = createServiceRef<Logger>({
   id: 'core.logger',
 });
diff --git a/packages/backend-plugin-api/src/services/definitions/permissionsServiceRef.ts b/packages/backend-plugin-api/src/services/definitions/permissionsServiceRef.ts
index 4355286611..b13ca9e240 100644
--- a/packages/backend-plugin-api/src/services/definitions/permissionsServiceRef.ts
+++ b/packages/backend-plugin-api/src/services/definitions/permissionsServiceRef.ts
@@ -20,6 +20,9 @@ import {
   PermissionEvaluator,
 } from '@backstage/plugin-permission-common';
 
+/**
+ * @public
+ */
 export const permissionsServiceRef = createServiceRef<
   PermissionEvaluator | PermissionAuthorizer
 >({
diff --git a/packages/backend-plugin-api/src/services/definitions/schedulerServiceRef.ts b/packages/backend-plugin-api/src/services/definitions/schedulerServiceRef.ts
index 3a3abfcc10..ca442dd34d 100644
--- a/packages/backend-plugin-api/src/services/definitions/schedulerServiceRef.ts
+++ b/packages/backend-plugin-api/src/services/definitions/schedulerServiceRef.ts
@@ -17,6 +17,9 @@
 import { createServiceRef } from '../system/types';
 import { PluginTaskScheduler } from '@backstage/backend-tasks';
 
+/**
+ * @public
+ */
 export const schedulerServiceRef = createServiceRef<PluginTaskScheduler>({
   id: 'core.scheduler',
 });
diff --git a/packages/backend-plugin-api/src/services/definitions/scheldulerServiceRef.ts b/packages/backend-plugin-api/src/services/definitions/scheldulerServiceRef.ts
index 4355286611..b13ca9e240 100644
--- a/packages/backend-plugin-api/src/services/definitions/scheldulerServiceRef.ts
+++ b/packages/backend-plugin-api/src/services/definitions/scheldulerServiceRef.ts
@@ -20,6 +20,9 @@ import {
   PermissionEvaluator,
 } from '@backstage/plugin-permission-common';
 
+/**
+ * @public
+ */
 export const permissionsServiceRef = createServiceRef<
   PermissionEvaluator | PermissionAuthorizer
 >({
diff --git a/packages/backend-plugin-api/src/services/definitions/tokenManagerServiceRef.ts b/packages/backend-plugin-api/src/services/definitions/tokenManagerServiceRef.ts
index c62d4bb634..6995033e81 100644
--- a/packages/backend-plugin-api/src/services/definitions/tokenManagerServiceRef.ts
+++ b/packages/backend-plugin-api/src/services/definitions/tokenManagerServiceRef.ts
@@ -17,6 +17,9 @@
 import { createServiceRef } from '../system/types';
 import { TokenManager } from '@backstage/backend-common';
 
+/**
+ * @public
+ */
 export const tokenManagerServiceRef = createServiceRef<TokenManager>({
   id: 'core.tokenManager',
 });
diff --git a/packages/backend-plugin-api/src/services/definitions/urlReaderServiceRef.ts b/packages/backend-plugin-api/src/services/definitions/urlReaderServiceRef.ts
index 25a9666882..ebb32f1aed 100644
--- a/packages/backend-plugin-api/src/services/definitions/urlReaderServiceRef.ts
+++ b/packages/backend-plugin-api/src/services/definitions/urlReaderServiceRef.ts
@@ -17,6 +17,9 @@
 import { createServiceRef } from '../system/types';
 import { UrlReader } from '@backstage/backend-common';
 
+/**
+ * @public
+ */
 export const urlReaderServiceRef = createServiceRef<UrlReader>({
   id: 'core.urlReader',
 });
diff --git a/packages/backend-plugin-api/src/services/system/types.ts b/packages/backend-plugin-api/src/services/system/types.ts
index 2f59e65320..30d8d94c11 100644
--- a/packages/backend-plugin-api/src/services/system/types.ts
+++ b/packages/backend-plugin-api/src/services/system/types.ts
@@ -56,6 +56,9 @@ export type AnyServiceFactory = ServiceFactory<
   { [key in string]: unknown }
 >;
 
+/**
+ * @public
+ */
 export function createServiceRef<T>(options: { id: string }): ServiceRef<T> {
   return {
     id: options.id,
@@ -69,6 +72,9 @@ export function createServiceRef<T>(options: { id: string }): ServiceRef<T> {
   };
 }
 
+/**
+ * @public
+ */
 export function createServiceFactory<
   Api,
   Impl extends Api,