Skip to content

Commit

Permalink
chore(core): add dev feature tag for openapi.json (#6025)
Browse files Browse the repository at this point in the history
chore(core): add dev feature tag for openapi.json to indicate operation should not show up in swagger.json
  • Loading branch information
darcyYe authored Jun 21, 2024
1 parent 7f9c0f2 commit 651a027
Show file tree
Hide file tree
Showing 2 changed files with 22 additions and 9 deletions.
4 changes: 2 additions & 2 deletions packages/core/src/routes/swagger/index.ts
Original file line number Diff line number Diff line change
Expand Up @@ -25,7 +25,7 @@ import {
buildTag,
findSupplementFiles,
normalizePath,
removeCloudOnlyOperations,
removeUnnecessaryOperations,
validateSupplement,
validateSwaggerDocument,
} from './utils/general.js';
Expand Down Expand Up @@ -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>
)
Expand Down
27 changes: 20 additions & 7 deletions packages/core/src/routes/swagger/utils/general.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -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.`
);
}
}
Expand Down Expand Up @@ -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];
}
Expand Down

0 comments on commit 651a027

Please sign in to comment.