chore(core): add dev feature tag for openapi.json (#6025)

chore(core): add dev feature tag for openapi.json to indicate operation should not show up in swagger.json

packages/core/src/routes/swagger/index.ts

@@ -25,7 +25,7 @@ import {
   buildTag,
   findSupplementFiles,
   normalizePath,
-  removeCloudOnlyOperations,
+  removeUnnecessaryOperations,
   validateSupplement,
   validateSwaggerDocument,
 } from './utils/general.js';
@@ -199,7 +199,7 @@ export default function swaggerRoutes<T extends AnonymousRouter, R extends Route
     const supplementPaths = await findSupplementFiles(routesDirectory);
     const supplementDocuments = await Promise.all(
       supplementPaths.map(async (path) =>
-        removeCloudOnlyOperations(
+        removeUnnecessaryOperations(
           // eslint-disable-next-line no-restricted-syntax -- trust the type here as we'll validate it later
           JSON.parse(await fs.readFile(path, 'utf8')) as DeepPartial<OpenAPIV3.Document>
         )

packages/core/src/routes/swagger/utils/general.ts

@@ -14,6 +14,8 @@ const capitalize = (value: string) => value.charAt(0).toUpperCase() + value.slic
 
 /** The tag name used in the supplement document to indicate that the operation is cloud only. */
 const cloudOnlyTag = 'Cloud only';
+/** The tag name is used in the supplement document to indicate that the corresponding API operation is a dev feature. */
+const devFeatureTag = 'Dev feature';
 
 /**
  * Get the root component name from the given absolute path.
@@ -114,10 +116,12 @@ const validateSupplementPaths = (
         if (
           isKeyInObject(operation, 'tags') &&
           Array.isArray(operation.tags) &&
-          (operation.tags.length > 1 || operation.tags[0] !== cloudOnlyTag)
+          !operation.tags.every(
+            (tag) => typeof tag === 'string' && [cloudOnlyTag, devFeatureTag].includes(tag)
+          )
         ) {
           throw new TypeError(
-            `Cannot use \`tags\` in supplement document on path \`${path}\` and operation \`${method}\` except for tag \`${cloudOnlyTag}\`.  Define tags in the document root instead.`
+            `Cannot use \`tags\` in supplement document on path \`${path}\` and operation \`${method}\` except for tag \`${cloudOnlyTag}\` and \`${devFeatureTag}\`. Define tags in the document root instead.`
           );
         }
       }
@@ -218,19 +222,28 @@ export const validateSwaggerDocument = (document: OpenAPIV3.Document) => {
  * **CAUTION**: This function mutates the input document.
  *
  * Remove operations (path + method) that are tagged with `Cloud only` if the application is not
- * running in the cloud. This will prevent the swagger validation from failing in the OSS
- * environment.
+ * running in the cloud and remove operations with `Dev feature` tag if Logto's `isDevFeatureEnabled` flag
+ * is set to be false.
+ *
+ * This will prevent the swagger validation from failing in the OSS environment.
+ *
  */
-export const removeCloudOnlyOperations = (
+// eslint-disable-next-line complexity
+export const removeUnnecessaryOperations = (
   document: DeepPartial<OpenAPIV3.Document>
 ): DeepPartial<OpenAPIV3.Document> => {
-  if (EnvSet.values.isCloud || !document.paths) {
+  const { isCloud, isDevFeaturesEnabled } = EnvSet.values;
+  if ((isCloud && isDevFeaturesEnabled) || !document.paths) {
     return document;
   }
 
   for (const [path, pathItem] of Object.entries(document.paths)) {
     for (const method of Object.values(OpenAPIV3.HttpMethods)) {
-      if (pathItem?.[method]?.tags?.includes(cloudOnlyTag)) {
+      if (
+        // eslint-disable-next-line @typescript-eslint/prefer-nullish-coalescing
+        (!isCloud && pathItem?.[method]?.tags?.includes(cloudOnlyTag)) ||
+        (!isDevFeaturesEnabled && pathItem?.[method]?.tags?.includes(devFeatureTag))
+      ) {
         // eslint-disable-next-line @silverhand/fp/no-delete, @typescript-eslint/no-dynamic-delete -- intended
         delete pathItem[method];
       }