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

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

@@ -25,7 +25,7 @@ import {
  buildTag,
  findSupplementFiles,
  normalizePath,
- removeCloudOnlyOperations,
+ removeUnnecessaryOperations,
  validateSupplement,
  validateSwaggerDocument,
 } from './utils/general.js';
@@ -196,7 +196,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 @@
 
 /** 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 @@
  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.`
  );
  }
  }
@@ -216,19 +220,28 @@
  * **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];
  }