refactor: add changeset and improve code

.changeset/heavy-badgers-jog.md

@@ -0,0 +1,8 @@
+---
+"@logto/core": patch
+---
+
+fix OpenAPI schema returned by the `GET /api/swagger.json` endpoint
+
+1. The `:` character is invalid in parameter names, such as `organizationId:root`. These characters have been replaced with `-`.
+2. The `tenantId` parameter of the `/api/.well-known/endpoints/{tenantId}` route was missing from the generated OpenAPI spec document, resulting in validation errors. This has been fixed.

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

@@ -236,9 +236,8 @@ export default function swaggerRoutes<T extends AnonymousRouter, R extends Route
           (previous, entityName) => ({
             ...previous,
             ...buildPathIdParameters(entityName),
-            ...customParameters(),
           }),
-          {}
+          customParameters()
         ),
       },
       tags: [...tags, ...additionalTags].map((tag) => ({ name: tag })),

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

@@ -253,11 +253,10 @@ export const buildPathIdParameters = (
 };
 
 /**
- * Build a parameter object for the `tenantId` parameter.
+ * Build a parameter object with additional parameters that are not inferred from the path.
- * @returns The parameter object for the `tenantId` parameter.
  */
 export const customParameters = (): Record<string, OpenAPIV3.ParameterObject> => {
-  return {
+  return Object.freeze({
     tenantId: {
       name: 'tenantId',
       in: 'path',
@@ -267,5 +266,5 @@ export const customParameters = (): Record<string, OpenAPIV3.ParameterObject> =>
         type: 'string',
       },
     },
-  };
+  });
 };